Examples¶
Start with Quick Start for one forward simulation and its gradient, then choose the example closest to your task. Each script can be read and run independently; you do not need to work through the whole collection.
Task | Example |
|---|---|
Recover a velocity model | FWI in one file — self-contained FWI |
Image reflectors | Reverse-Time Migration (RTM) — reverse-time migration |
Work with elastic waves | Elastic propagation and FWI — modelling and inversion |
Simulate an ultrasound array | Ultrasound and NDT (coming from k-Wave) — transducers and fluid-solid media |
Reconstruct initial pressure | Photoacoustic initial-pressure reconstruction — an initial-state inverse problem |
Fit a simulation into available memory | 3D FWI with storage options to reduce memory usage and Further reducing memory consumption with checkpointing |
The examples import packages that Deepwave itself does not need – plotting, array and signal-processing libraries, and a few alternatives they compare against. Install them all with:
pip install 'deepwave[examples]'
Two of the examples below – the moment-tensor one and the elastic Born recipe – specify their surveys with the channel-keyed sources=/ receivers= mapping form, which is the canonical way to do it (see Usage). The rest use the equivalent flat source_amplitudes_*/source_locations_* keywords, deliberately: that form is permanent, and converting every example would suggest otherwise.
For a larger seismic survey using downloaded data, see Forward modelling with Marmousi velocity model and the data preparation instructions below.
The examples in the first group are self-contained (they generate their own models and data, so you can run them immediately). The examples in the second group, plus the two fuller distributed-execution examples linked from Distributed (multi-GPU) execution, use the Marmousi velocity model and therefore require two data files, marmousi_vp.bin and marmousi_data.bin, in the directory you run them from (the download and conversion steps are described at the top of the forward modelling example). The short version: run python docs/get_marmousi.py once from that directory – it downloads the model from its original source and generates the synthetic data file with Deepwave itself; see Forward modelling with Marmousi velocity model for what it does and why Deepwave does not ship these files directly. As of Deepwave 0.1.0 marmousi_vp.bin’s on-disk layout is depth-first (751 x 2301, dimension 0 = depth, matching Dimension order and the axis convention), so a copy downloaded with an earlier version must be regenerated by re-running python docs/get_marmousi.py. Every one of those examples reads the two files through load_vp and load_data in docs/get_marmousi.py rather than opening them itself, so the layout, the staleness check and the error message when a file is missing are the same in all of them.
Running the examples¶
Each example is a plain Python script under docs/ in the source repository, runnable directly:
cd docs
python example_forward_model.py
Beyond Deepwave itself the scripts use matplotlib to draw their figures, and some use scipy (smoothing, filter design) or torchaudio (applying those filters). None of those is needed to use Deepwave: its only dependency is PyTorch. Install what an example imports if you want to run it.
Every example also honours the DEEPWAVE_SMOKE environment variable:
DEEPWAVE_SMOKE=1 python example_fwi.py
Setting DEEPWAVE_SMOKE=1 shrinks the example – fewer shots, fewer receivers, fewer time steps, a smaller grid, fewer iterations – so that it finishes in seconds instead of minutes, while still running the same code path and still checking at the end that it produced a sensible result. For the Marmousi examples it also replaces the downloaded model with a generated stand-in of the same shape and velocity range, so they can be run this way without downloading anything. It is meant for checking that an example runs, not for producing the figures on these pages: at those sizes the results are not representative, and the figures here all come from the default, full-size settings.
To run the whole set as one check, from the top of the repository:
python scripts/run_examples_smoke.py
That runs every example that needs nothing but a CPU, and reports which ones it skipped and why. Examples that need a GPU, or two of them, are skipped unless requested with --include gpu or --include multi_gpu.
Ultrasound and NDT users should also see Ultrasound and NDT (coming from k-Wave), whose worked example (docs/example_ultrasound.py) covers focused transducer arrays, tone-burst excitation, and fluid-solid interfaces.
Four of the self-contained examples below (generated model, elastic, photoacoustic, and FWI recipes) are also available as Jupyter notebooks, paired with their .py source via jupytext (see CONTRIBUTING.md for the regeneration command), and can be run directly in Google Colab – the first cell installs Deepwave, no local setup required:
| |
| |
| |
|
Self-contained
- FWI in one file
- Generated model
- Elastic propagation and FWI
- Earthquake (moment tensor) sources
- Photoacoustic initial-pressure reconstruction
- 3D FWI with storage options to reduce memory usage
- Further reducing memory consumption with checkpointing
- Using Batched Models
- Visualising wavefields and gradients with callbacks
- Matching a target final wavefield
- Location interpolation and dipoles
- Frequency tapering and time padding
- Time-dispersion correction
- Distributed (multi-GPU) execution
- Flagship 3-D FWI at a size that does not fit on one GPU
- Large gradients at edges
- Graph Space Optimal Transport
- Hessian
- FWI in other parameterisations
- FWI Recipes: Exotic Misfits, Deep Priors, and Uncertainty
- Source encoding for stochastic FWI
- Using torch.func features
- LSRTM with the variable-density acoustic Born propagator
- First-class boundary faces (free, rigid, periodic)
- Elastic free-surface topography (surface_method=”pm”)
- Q (attenuation) inversion with the viscoacoustic propagator
- Thomsen-space FWI with the pseudo-acoustic VTI propagator