Deepwave

Deepwave provides PyTorch-integrated wave propagators for forward modelling and backpropagation, for gradient calculation in inversion and optimisation tasks. It supports standard and Born modelling of the scalar, variable-density acoustic, and elastic wave equations in 1D, 2D, and 3D, with viscoacoustic attenuation in 1D–3D and VTI anisotropy in 2D and 3D. The compiled backends support CPUs and CUDA GPUs. See the capability matrix for exactly which options each propagator supports. New to seismic/wave-equation terminology? The Glossary defines the terms (PML, CFL, Born, FWI, and more) used throughout these docs.

Installation

Deepwave requires Python 3.9 or later and PyTorch 2.4 or later. Install PyTorch for your CPU or CUDA device by following the instructions on the PyTorch website, then install Deepwave:

python -m pip install deepwave

This method should work for most users. However, if you have an unusual system configuration, you might need to build Deepwave from source. Instructions for building from source are provided below.

macOS wheels support Apple Silicon. Intel Mac wheels are no longer built, because PyTorch 2.4 and newer do not provide Intel macOS wheels.

PyTorch is Deepwave’s only dependency. Nothing else is needed to use it. The example scripts under docs/ do import a few other packages – matplotlib to draw their figures, and, in some of them, scipy (smoothing and filter design) and torchaudio (applying those filters) – but those are needed only to run the examples, never by Deepwave itself. See Running the examples.

Deepwave is built on PyTorch, so understanding PyTorch well makes it easier to use. The PyTorch website offers many helpful tutorials, and the PyTorch page here covers the specific parts that matter most for Deepwave.

Building from source

Deepwave uses cibuildwheel and scikit-build-core for its build process. When you run pip install deepwave, pip will first attempt to download a precompiled wheel if one is available for your system. If a suitable precompiled wheel is not found, pip will automatically download the source distribution and attempt to compile it on your system. You will need to have a C compiler and CMake available, and a CUDA compiler if you wish to have CUDA support.

If you wish to force building from source rather than using a wheel, you can use the following command:

python -m pip install --force-reinstall --no-deps --no-binary deepwave deepwave

This replaces an existing installation with a source build, leaving your chosen PyTorch installation in place. It is the recommended fix if a precompiled wheel does not run on your CPU (see Installation troubleshooting below).

Installation troubleshooting

Prebuilt x86 wheels require AVX2. On a CPU without it, current wheels report the missing instruction set; older wheels may crash with Illegal instruction (core dumped). A source build uses a portable CPU baseline by default. See Troubleshooting for this and other installation and runtime problems.

Citing

Deepwave is archived on Zenodo with the DOI 10.5281/zenodo.3829886 (this DOI always resolves to the latest release). If you would like to cite Deepwave, I suggest:

@software{richardson_alan_2026,
  author       = {Richardson, Alan},
  title        = {Deepwave},
  year         = 2026,
  publisher    = {Zenodo},
  version      = {0.1.0},
  doi          = {10.5281/zenodo.3829886},
  url          = {https://doi.org/10.5281/zenodo.3829886}
}

Support

If you encounter any issues (e.g., typos, broken links, unexpected behaviour, examples that don’t work), or have suggestions for improvement, please file an issue on GitHub or send an email.

Getting started

User guide

API reference

Propagator reference

Theory and guarantees

Derivations (developer reference)

Design notes (developer reference)

Applications and alternatives

Release reference (maintainer)