<div align="center">
<img src="docs/assets/images/jwave_logo.png" alt="logo"></img>
</div>
# j-Wave: Differentiable acoustic simulations in JAX
[](https://discord.gg/VtUb4fFznt)
[](LICENSE)
[](https://github.com/ucl-bug/jwave/actions/workflows/ci_tests.yml)
[](https://codecov.io/gh/ucl-bug/jwave)
[](https://mybinder.org/v2/gh/ucl-bug/jwave/main?labpath=docs%2Fnotebooks%2Fivp%2Fhomogeneous_medium.ipynb)
[](https://colab.research.google.com/drive/1xAHAognF1v9un6GNvaGPSfdVeCDK8l9z?usp=sharing)
[Install](#install) | [Tutorials](https://ucl-bug.github.io/jwave/notebooks/ivp/homogeneous_medium.html) | [Documentation](https://ucl-bug.github.io/jwave) | [Changelog](HISTORY.md)
j-Wave is a library of simulators for acoustic applications. It is heavily inspired by [k-Wave](http://www.k-wave.org/)—a substantial portion of j-Wave is a port of k-Wave in JAX—and it's intended to be used as a collection of modular blocks that can be easily incorporated into any machine learning pipeline.
Embracing the philosophy of [JAX](https://jax.readthedocs.io/en/stable/), j-Wave is developed with the following principles in mind:
1. To be differentiable
2. To be efficient through `jit` compilation
3. To be easily run on GPUs
4. To be easily customizable
<br/>
## Install
Follow the instructions to install [Jax with CUDA support](https://github.com/google/jax#installation) if you wish to use your GPU.
Next, simply install `jwave` using pip:
```bash
pip install jwave
```
For more information, refer to the [Linux installation guide](docs/install/on_linux.md).
Due to JAX's limited support on Windows, j-Wave can only be run on Windows machines using the Windows Subsystem for Linux. Please refer to the [Installation on Windows guide](docs/install/on_win.md) for more details.
<br/>
## Example
This example simulates an acoustic initial value problem, which is often used as a simple model for photoacoustic acquisitions:
```python
from jax import jit
from jwave import FourierSeries
from jwave.acoustics.time_varying import simulate_wave_propagation
from jwave.geometry import Domain, Medium, TimeAxis
from jwave.utils import load_image_to_numpy
# Simulation parameters
N, dx = (256, 256), (0.1e-3, 0.1e-3)
domain = Domain(N, dx)
medium = Medium(domain=domain, sound_speed=1500.)
time_axis = TimeAxis.from_medium(medium, cfl=0.3, t_end=.8e-05)
# Initial pressure field
p0 = load_image_to_numpy("docs/assets/images/jwave.png", image_size=N)/255.
p0 = FourierSeries(p0, domain)
# Compile and run the simulation
@jit
def solver(medium, p0):
return simulate_wave_propagation(medium, time_axis, p0=p0)
pressure = solver(medium, p0)
```
## Support
[](https://discord.gg/VtUb4fFznt)
If you encounter any problems with the code or wish to propose new features, please feel free to open an issue. If you need general guidance, wish to discuss something, or just want to say hi, don't hesitate to leave a message in our [Discord channel](https://discord.gg/VtUb4fFznt).
<br/>
## Contributing
Contributions are absolutely welcome! Most contributions start with an issue. Please don't hesitate to create issues in which you ask for features, give feedback on performances, or simply want to reach out.
To make a pull request, please look at the detailed [Contributing guide](CONTRIBUTING.md) for how to do it, but fundamentally keep in mind the following main guidelines:
- If you add a new feature or fix a bug:
- Make sure it is covered by tests
- Add a line in the changelog using `kacl-cli`
- If you changed something in the documentation, make sure that the documentation site can be correctly build using `mkdocs serve`
<br/>
## Citation
[](https://arxiv.org/abs/2207.01499)
If you use `jwave` for your research, please consider citing it as:
```bibtex
@article{stanziola2022jwave,
author={Stanziola, Antonio and Arridge, Simon R. and Cox, Ben T. and Treeby, Bradley E.},
title = {j-Wave: An open-source differentiable wave simulator},
publisher = {arXiv},
year = {2022},
}
```
<br/>
## Related Projects
1. [`ADSeismic.jl`](https://github.com/kailaix/ADSeismic.jl): a finite difference acoustic simulator with support for AD and JIT compilation in Julia.
2. [`stride`](https://github.com/trustimaging/stride): a general optimisation framework for medical ultrasound tomography.
3. [`k-wave-python`](https://github.com/waltsims/k-wave-python): A python interface to k-wave GPU accelerated binaries
Raw data
{
"_id": null,
"home_page": "",
"name": "jwave",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "jax,acoustics,simulation,ultrasound,differentiable-programming",
"author": "Antonio Stanziola",
"author_email": "a.stanziola@ucl.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/7b/13/aa7f6aaaa4341fc7a4a5c895b8857785d8a2382fbdda8c38dd5ed420561a/jwave-0.2.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n<img src=\"docs/assets/images/jwave_logo.png\" alt=\"logo\"></img>\n</div>\n\n# j-Wave: Differentiable acoustic simulations in JAX\n\n[](https://discord.gg/VtUb4fFznt)\n[](LICENSE)\n[](https://github.com/ucl-bug/jwave/actions/workflows/ci_tests.yml)\n[](https://codecov.io/gh/ucl-bug/jwave)\n[](https://mybinder.org/v2/gh/ucl-bug/jwave/main?labpath=docs%2Fnotebooks%2Fivp%2Fhomogeneous_medium.ipynb)\n[](https://colab.research.google.com/drive/1xAHAognF1v9un6GNvaGPSfdVeCDK8l9z?usp=sharing)\n\n[Install](#install) | [Tutorials](https://ucl-bug.github.io/jwave/notebooks/ivp/homogeneous_medium.html) | [Documentation](https://ucl-bug.github.io/jwave) | [Changelog](HISTORY.md)\n\nj-Wave is a library of simulators for acoustic applications. It is heavily inspired by [k-Wave](http://www.k-wave.org/)\u2014a substantial portion of j-Wave is a port of k-Wave in JAX\u2014and it's intended to be used as a collection of modular blocks that can be easily incorporated into any machine learning pipeline.\n\nEmbracing the philosophy of [JAX](https://jax.readthedocs.io/en/stable/), j-Wave is developed with the following principles in mind:\n\n1. To be differentiable\n2. To be efficient through `jit` compilation\n3. To be easily run on GPUs\n4. To be easily customizable\n\n\n<br/>\n\n## Install\n\nFollow the instructions to install [Jax with CUDA support](https://github.com/google/jax#installation) if you wish to use your GPU.\n\nNext, simply install `jwave` using pip:\n\n```bash\npip install jwave\n```\n\nFor more information, refer to the [Linux installation guide](docs/install/on_linux.md).\n\nDue to JAX's limited support on Windows, j-Wave can only be run on Windows machines using the Windows Subsystem for Linux. Please refer to the [Installation on Windows guide](docs/install/on_win.md) for more details.\n\n<br/>\n\n## Example\n\nThis example simulates an acoustic initial value problem, which is often used as a simple model for photoacoustic acquisitions:\n\n```python\nfrom jax import jit\n\nfrom jwave import FourierSeries\nfrom jwave.acoustics.time_varying import simulate_wave_propagation\nfrom jwave.geometry import Domain, Medium, TimeAxis\nfrom jwave.utils import load_image_to_numpy\n\n# Simulation parameters\nN, dx = (256, 256), (0.1e-3, 0.1e-3)\ndomain = Domain(N, dx)\nmedium = Medium(domain=domain, sound_speed=1500.)\ntime_axis = TimeAxis.from_medium(medium, cfl=0.3, t_end=.8e-05)\n\n# Initial pressure field\np0 = load_image_to_numpy(\"docs/assets/images/jwave.png\", image_size=N)/255.\np0 = FourierSeries(p0, domain)\n\n# Compile and run the simulation\n@jit\ndef solver(medium, p0):\n return simulate_wave_propagation(medium, time_axis, p0=p0)\n\npressure = solver(medium, p0)\n```\n\n\n\n\n## Support\n\n[](https://discord.gg/VtUb4fFznt)\n\nIf you encounter any problems with the code or wish to propose new features, please feel free to open an issue. If you need general guidance, wish to discuss something, or just want to say hi, don't hesitate to leave a message in our [Discord channel](https://discord.gg/VtUb4fFznt).\n\n<br/>\n\n## Contributing\n\nContributions are absolutely welcome! Most contributions start with an issue. Please don't hesitate to create issues in which you ask for features, give feedback on performances, or simply want to reach out.\n\nTo make a pull request, please look at the detailed [Contributing guide](CONTRIBUTING.md) for how to do it, but fundamentally keep in mind the following main guidelines:\n\n- If you add a new feature or fix a bug:\n - Make sure it is covered by tests\n - Add a line in the changelog using `kacl-cli`\n- If you changed something in the documentation, make sure that the documentation site can be correctly build using `mkdocs serve`\n\n<br/>\n\n\n## Citation\n\n[](https://arxiv.org/abs/2207.01499)\n\nIf you use `jwave` for your research, please consider citing it as:\n\n```bibtex\n@article{stanziola2022jwave,\n author={Stanziola, Antonio and Arridge, Simon R. and Cox, Ben T. and Treeby, Bradley E.},\n title = {j-Wave: An open-source differentiable wave simulator},\n publisher = {arXiv},\n year = {2022},\n}\n```\n\n<br/>\n\n## Related Projects\n\n1. [`ADSeismic.jl`](https://github.com/kailaix/ADSeismic.jl): a finite difference acoustic simulator with support for AD and JIT compilation in Julia.\n2. [`stride`](https://github.com/trustimaging/stride): a general optimisation framework for medical ultrasound tomography.\n3. [`k-wave-python`](https://github.com/waltsims/k-wave-python): A python interface to k-wave GPU accelerated binaries\n",
"bugtrack_url": null,
"license": "LGPL-3.0-only",
"summary": "Fast and differentiable acoustic simulations in JAX.",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/ucl-bug/jwave/issues",
"Homepage": "https://ucl-bug.github.io/jwave/",
"Repository": "https://github.com/ucl-bug/jwave",
"Support": "https://discord.gg/VtUb4fFznt"
},
"split_keywords": [
"jax",
"acoustics",
"simulation",
"ultrasound",
"differentiable-programming"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "77ecbf3f0581dd5a2d0c9408dfc94c78575cbc13d303fa912706c30b2a120926",
"md5": "5a19adc1eab1c72f004725d441ced4b2",
"sha256": "bd55571c940988506ff06c6ca9493fb3f96a56c9ea01f549796dc97e2331bcee"
},
"downloads": -1,
"filename": "jwave-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5a19adc1eab1c72f004725d441ced4b2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 40386,
"upload_time": "2023-12-18T15:23:01",
"upload_time_iso_8601": "2023-12-18T15:23:01.252108Z",
"url": "https://files.pythonhosted.org/packages/77/ec/bf3f0581dd5a2d0c9408dfc94c78575cbc13d303fa912706c30b2a120926/jwave-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7b13aa7f6aaaa4341fc7a4a5c895b8857785d8a2382fbdda8c38dd5ed420561a",
"md5": "fcecd583b3a56f311d8df3ae9808409a",
"sha256": "d936a0f6ed8b9b529a5b6fd5901383268166263f07028de36d2d614a72c7626a"
},
"downloads": -1,
"filename": "jwave-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "fcecd583b3a56f311d8df3ae9808409a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 33790,
"upload_time": "2023-12-18T15:23:03",
"upload_time_iso_8601": "2023-12-18T15:23:03.038158Z",
"url": "https://files.pythonhosted.org/packages/7b/13/aa7f6aaaa4341fc7a4a5c895b8857785d8a2382fbdda8c38dd5ed420561a/jwave-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-18 15:23:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ucl-bug",
"github_project": "jwave",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jwave"
}
JSON
