Examples

All examples on GitHub — examples/ (clone, run, modify)

Runnable example scripts and notebooks live in the examples/ directory of the repository. The notebooks under docs/notebooks/ (cards below) are cell-by-cell tutorials and the easiest entry point. Scripts for workflows that don't fit a notebook (e.g. multi-process multi-GPU FWI) are linked at the bottom of this page.

Notebooks (start here)

• 

  Hello · SWEEP

  ---

  Smallest end-to-end SWEEP story in one notebook: parameters → model → Acoustic() + PropTorch() → one shot gather → one .backward() for a vp gradient → 5-line Adam loop. No external data.

  Open notebook

• 

  FWI · Acoustic · Marmousi

  ---

  Load Marmousi from sweep.datasets, build a 192×320 window, forward-model observed gathers, and invert the smooth start with Adam + MSE. Each phase is one cell.

  Open notebook

• 

  FWI · Elastic · Marmousi

  ---

  Same skeleton, but the equation is Elastic and the model is the (vp, vs, rho) triplet. vs and rho are derived from vp with Poisson + Gardner relations so the example still runs with zero downloads.

  Open notebook

• 

  FWI · multiscale

  ---

  Three-band frequency progression (3 → 6 → 12 Hz) of acoustic FWI on Marmousi 25 m. Each band feeds its final model into the next; loss drops monotonically across the chain and avoids cycle skipping.

  Open notebook

• 

  FWI · Frequency-selection encoding

  ---

  A towed-streamer survey, 129 shots every 100 m, all in one forward: each shot radiates its own monochromatic frequency, the steady-window DFT separates them with zero crosstalk, and a coherence misfit cancels the wavelet. Multiscale 1.5–3 / 2.5–5 / 4–10 Hz, each band on its own grid and time step (100 / 50 / 25 m), in plain torch on Marmousi.

  Open notebook

• 

  FWI · Batched per-shot local windows

  ---

  A fixed streamer makes every shot's model window the same width, so all the crops stack into one batched solver call and the overlapping windows scatter-add back onto the full model through autograd. Frequency continuation recovers Marmousi from a smooth start on one GPU.

  Open notebook

• 

  DAS · Zhao vs Mu

  ---

  Forward-model the same three-layer elastic medium with the two DAS formulations and compare the resulting strain-rate gathers side by side.

  Open notebook

• 

  Wavefield · VTI + shear suppression

  ---

  Run Duveneck (1st-order), Liang (2nd-order pseudo-acoustic), and Alkhalifah (η-acoustic) through the unified AcousticAniso factory on the canonical Duveneck Fig 2 setup; the trailing cell demonstrates the δ→ε disk taper that kills the pseudo-acoustic shear artefact.

  Open notebook

• 

  Wavefield · Elastic

  ---

  Wavefield snapshots from three different stress-source loadings on a uniform elastic medium — explosion, vertical dipole, and pure shear — to visualize P/S excitation and radiation patterns.

  Open notebook

• 

  Memory · strategies

  ---

  Same forward + backward step run under every memory strategy (eager full / chunk-ckpt / boundary-saving on gpu × dtype vs. c full / boundary-saving on {gpu, cpu, disk} × dtype / chunk-ckpt / recursive-ckpt) with side-by-side peak-memory and wallclock charts.

  Open notebook

• 

  RTM · Acoustic · Marmousi

  ---

  Reverse-time migration on full 12.5 m Marmousi with a 15 Hz Ricker — the RTM image as the gradient of an inner-product loss through the boundary-saving backward, with background subtraction, near-offset mask and illumination compensation. A clean reflectivity image in <3 s on 30 shots.

  Open notebook

• 

  Solver · hyperparameters

  ---

  Side-by-side wavefield snapshots showing how the propagator's spatial_order, abcn (PML width) and pml_type choices visibly change boundary reflections and grid dispersion on a single shot.

  Open notebook

• 

  Wavefield · Elastic TTI

  ---

  Rotated staggered-grid (ElasticTTI) vz snapshots across three tilt / azimuth cases — the Duveneck Fig 2 setup at full resolution with (ε, δ, γ, θ, φ) rotated symmetry axis.

  Open notebook

• 

  Wavefield · Elastic TTI · 3-D

  ---

  ElasticTTISG3D on a 2.88 km cube: vz through the source plane for a VTI reference and two rotated axes. In 3-D the azimuth stops being decorative — at φ = 45° the qP front leaves the x–z plane, which no 2-D run can show.

  Open notebook

• 

  Wavefield · Elastic TTI · displacement (Oh 2020)

  ---

  ElasticTTI2nd: two displacements on a triple time buffer instead of three velocities and five stresses, with the hierarchical (vh, η) parametrisation of Oh et al. 2020. Three tilts, cross-checked against ElasticTTISG on the qP wavefront.

  Open notebook

• 

  FWI · 3-D · Overthrust

  ---

  Acoustic FWI on a 3-D Overthrust volume — Acoustic3D solver on impl='eager', chunked checkpointing for memory, depth/inline/crossline slices of the recovered vp cube vs ground truth.

  Open notebook

• 

  Multi-GPU · DDP vs 1 GPU

  ---

  torchrun --nproc_per_node=N driver that shards shots across GPUs and syncs gradients via torch.distributed, timed against a single-GPU baseline on a two-layer toy model (the saved run: 3.53× on 4 GPUs).

  Open notebook

• 

  IFWI · SIREN coordinate network

  ---

  Implicit FWI: a SIREN coordinate network outputs vp(x, z) instead of a grid of free parameters; its weights are inverted by backprop through the propagator on Marmousi.

  Open notebook

• 

  Custom gradients · imaging condition

  ---

  Register your own imaging condition — override the default correlation with a user-defined gradient kernel via the autograd hook and compare it to the built-in one.

  Open notebook

• 

  Wavefield · irregular topography

  ---

  Image-method irregular free-surface for acoustic & elastic 2-D — drape a non-flat surface along the top of the model and see how the topography reshapes the surface waves and primaries.

  Open notebook

• 

  Wavefield · Per-edge free surface

  ---

  free_surface takes a list of faces, not just a bool: free surface on any subset of the four edges — top-only, two-face corners, or a fully closed reverberant box (deepwave-style) — with gradients on every backward memory mode.

  Open notebook

• 

  Wavefield · Visco-acoustic · constant-Q

  ---

  ViscoAcoustic: the acoustic solver plus Zhu & Harris (2014) decoupled attenuation — a dispersion switch that moves the front and a damping switch that decays it, each demonstrated alone, with the measured decay checked against constant-Q theory.

  Open notebook

• 

  Wavefield · Visco-elastic · GSLS

  ---

  ViscoElastic: the elastic solver plus the generalized standard linear solid SPECFEM2D uses — Qp and Qs switched independently, one quadrant per combination, the P/S decay checked against constant-Q theory, and why dispersion and attenuation cannot be switched apart.

  Open notebook

• 

  HPC · Domain decomposition

  ---

  One model, several GPUs: ModelParallel slices it into tiles and exchanges a halo every step, so a single shot is solved cooperatively rather than replicated. Gradients are bit-identical to the single-domain run — the notebook checks that, tile by tile.

  Open notebook

• 

  HPC · DD on Overthrust 3-D

  ---

  The same split on a real 3-D benchmark, 2 × 2 tiles across four GPUs. The gradient is sliced three ways straight across the cut planes, where a halo bug would show as a stripe — and compared against the single-GPU answer.

  Open notebook

• 

  ADCIG · Poynting (custom backward)

  ---

  Angle-domain common-image gathers via a custom imaging condition plugged into the eager backward with register_gradient — Poynting-vector recipe. For the space-lag ADCIG (2D + 3D, CUDA compute_adcig) see the next card.

  Open notebook

• 

  ADCIG · space-lag (2D & 3D)

  ---

  Subsurface-offset extended imaging condition (Sava & Fomel) via the built-in CUDA compute_adcig toggle, then slant-stack to angle. Boundary-saving path, acoustic 2D & 3D.

  Open notebook

• 

  Elastic vector reflectivity

  ---

  Forward-modeling validation of elastic vector-reflectivity (Soares & Sacchi 2025) — the formulation reproduced and checked against the reference.

  Open notebook

• 

  FWI · VRZ · Marmousi

  ---

  Acoustic variable-density (VRZ) FWI on Marmousi — vector reflectivity from impedance, inverted with the AcousticVRZ equation.

  Open notebook

• 

  Extending · add a new equation

  ---

  Tutorial: add a brand-new wave equation to SWEEP — define its fields and time step, register it, and drive it through PropTorch like any built-in.

  Open notebook

• 

  FWI · boundary compression

  ---

  storage_dtype (fp16/bf16/int8) shrinks the saved boundary wavefield while compute stays FP32. Marmousi FWI across the full {gpu, cpu, disk} × dtype matrix on the compiled path, plus gpu × dtype on eager — identical convergence, plus a runtime GPU-memory breakdown.

  Open notebook

• 

  Sensitivity · Acoustic radiation

  ---

  Scattered-wavefield snapshots of the partial-derivative virtual sources for the acoustic (Vp, ρ) / (Vp, Iₚ) parameterizations — the angular sensitivity behind multiparameter trade-off. Reproduces Operto et al. (2013) Fig. 2.

  Open notebook

• 

  Sensitivity · Elastic radiation

  ---

  Elastic (Vp, Vs, ρ) P-P / P-S / S-S radiation patterns: the analytic Born kernel against sweep's Born-differenced numerics, the δln relative sizes (Vs/Vp ≈ 0.6), and scattered-wavefield snapshots. Cf. Operto Fig. 8(c,d) / Forgues & Lambaré.

  Open notebook

Scripts

For workflows that don't fit a single notebook — e.g. multi-process multi-GPU FWI — see:

• Multi-GPU DDP (fwi_marmousi_dist.py) — Torch torchrun driver that scales one-shot-per-rank across multiple GPUs and syncs gradients with torch.distributed.

• Model-parallel FWI (dd_fwi_marmousi_2d.py, dd_fwi_marmousi_elastic_2d.py, dd_fwi_overthrust_update.py) — the other axis: one model split across GPUs instead of one shot per GPU. Acoustic and elastic 2-D on Marmousi, plus a 3-D Overthrust model update. The two Marmousi scripts take --check <tag> to compare against an earlier run in --outdir (e.g. the same problem undivided, --px 1); the Overthrust script has no comparison mode.

Browse examples/ on GitHub for the full collection of runnable scripts.