PyFWI-Acoustic

PyFWI-Acoustic is a Python framework for 2D acoustic Full Waveform Inversion (FWI). Wave propagation and adjoint-state gradient computation run on the GPU through PyOpenCL, and the package includes time-lapse (4D) inversion strategies. It is adapted for two-parameter acoustic physics (Vp and rho) from the elastic PyFWI architecture (Mardan et al., 2023) with several improvements.

Features

• GPU wave physics: first-order velocity-pressure acoustic system on a staggered grid, 4th- or 8th-order finite differences, PML absorbing boundaries, OpenCL kernels.
• Discrete-adjoint gradients: the adjoint operator is the exact transpose of the discrete forward step. Both the conventional gradient and the second-order gradient are certified against central finite differences (see tests/).
• Acquisition geometries: surface, cross-well, and combined surveys via helpers in acquisition.py.
• Optimization: L-BFGS and conjugate-gradient drivers, plus truncated Gauss-Newton via Hessian-vector products (optimization.py).
• Gradient-norm objective (research module): minimize Phi = 1/2 ||grad_m J||^2 with exact second-order adjoints (fwi_second_order.py); derivation in theory/.
• Time-lapse FWI (tlfwi.py): parallel/independent, cascaded, double-difference, simultaneous (Tikhonov cross-regularization), and cross-updating strategies.

Installation

git clone https://github.com/hoyekan/PyFWI-Acoustic.git
cd PyFWI-Acoustic
pip install -e .

Optional extras:

pip install -e .[marmousi]   # requests + segyio, for downloading the Marmousi model
pip install -e .[torch]      # experimental PyTorch engine
pip install -e .[matlab]     # MATLAB v7.3 I/O

Dependencies: Python 3.8+, numpy, scipy, matplotlib, pyopencl (with a working OpenCL driver for your GPU or CPU).

After installation the modules are imported from the package, e.g.

from pyfwi_acoustic import acquisition as acq
from pyfwi_acoustic.wave_propagation import WavePropagator
from pyfwi_acoustic.fwi import FWI

Organization of the repository

PyFWI-Acoustic/
│
├── pyfwi_acoustic/               # main package
│   ├── __init__.py               # (empty file that marks this as a package)
│   ├── wave_propagation.py       # OpenCL forward/adjoint engine (1st- and 2nd-order gradients)
│   ├── fwi.py                    # first-order FWI driver  (J = 1/2 ||d_est - d_obs||^2)
│   ├── fwi_second_order.py       # gradient-norm objective (Phi = 1/2 ||grad_m J||^2)
│   ├── optimization.py           # optimizers + Hessian-vector products (Gauss-Newton / Newton-CG)
│   ├── tlfwi.py                  # time-lapse (4D) module
│   ├── fwi_tools.py              # cost functions, filters, parameter chain rules
│   ├── acquisition.py            # source wavelets & survey geometry
│   ├── processing.py             # residual preparation, muting
│   ├── model_dataset.py          # built-in earth models (Marmousi etc.)
│   ├── seismic_io.py             # data I/O
│   ├── seiplot.py                # plotting helpers
│   ├── rock_physics.py           # parameterization transforms
│   ├── wave_propagation_torch.py # PyTorch engine (autograd path, 8th-order stencils)
│   ├── torchfwi.py               # PyTorch FWI driver
│   └── kernels/                  # OpenCL kernel sources
│       ├── acoustic.cl
│       ├── acoustic_surface.cl
│       └── acoustic_crosswell.cl
│
├── tests/                        # certification suite
│   ├── gradient_check.py         #   FD/Taylor gradient certification, both objectives
│   ├── gradient_diagnose.py      #   per-pixel FD-vs-adjoint forensics
│   ├── adjoint_dot_test.py       #   machine-precision transpose test
│   ├── framework_verification.ipynb
│   └── README.md
│   .
│   .
│   . 
├── theory/                       #  mathematical Derivation of the Acoustic FWI Formulation for the first and second-order objective function.
│
├── setup.py
└── README.md

Quick start

See quick start.txt in example/. for a minimal end-to-end example, and the notebooks (gradient_example.ipynb, fwi_example_surface.ipynb, fwi_example_crosswell.ipynb, sensitivity.ipynb, marmousi_test.ipynb) for complete workflows.

Verification

Run after any change to the kernels or time-stepping loops:

python tests/adjoint_dot_test.py   # transpose exactness (~1e-8, seconds)
python tests/gradient_check.py     # FD certification of both objectives (minutes)

Citation

See CITATION.cff. This framework builds on PyFWI, which should be cited alongside it:

Mardan, A., Giroux, B., & Fabien-Ouellet, G. (2023). PyFWI: A Python package for full-waveform inversion and reservoir monitoring. SoftwareX, 22, 101384. doi:10.1016/j.softx.2023.101384

License

GPL-3.0 (see LICENSE). PyFWI-Acoustic is a derivative of PyFWI, which is distributed under GPL-3.0; this package therefore carries the same license.