Switch to Chinese

telefd3d

telefd3d is a 3D staggered-grid elastic finite-difference seismic wave propagation toolkit for flat free surfaces and Cao2018-style topography workflows on a regular Cartesian grid.

Search keywords: telefd3d, seismic, seismology, 3D elastic wave, finite difference, staggered grid, wave propagation, topography, CPML, geophysics. Repository: https://github.com/yangjudiao/telefd3d

Demo Gallery

This gallery uses two validated two-layer cases: a flat free-surface case and an XY-varying topography case.

Flat Free Surface: Wavefield Vz

Flat Free Surface: Surface Seismogram Vz

XY Topography: Wavefield Vz

XY Topography: Surface Seismogram Vz

Core Features

• 3D elastic velocity-stress FD solver on a staggered grid, implemented in Python with Numba acceleration.
• Unsplit CPML on the x/y side boundaries and the bottom boundary.
• Flat free surface and regular-grid topography workflow using PM-style redefined medium coefficients.
• Optional two-layer elastic medium with configurable lower-layer velocity and density.
• Delayed plane-stress source with controllable incident angle and azimuth.
• Relief-aware wavefield rendering with 3-view GIF export and centerline surface seismogram plots.
• Structured JSON metadata and streamed snapshot output for reproducible runs.

Technical Route

1. Governing Equations and Discretization

telefd3d uses the first-order velocity-stress elastic wave equations on a 3D staggered grid. This remains a practical baseline for heterogeneous media while keeping the solver layout explicit and inspectable.

2. Boundary Strategy

The x/y side walls and the bottom boundary use unsplit CPML. The implementation keeps separate memory variables for the stretched-derivative terms, which makes the absorber structure consistent with standard seismic CPML practice.

3. Free Surface and Topography Handling

The flat and topographic free-surface cases are handled through PM-style parameter redefinition on a regular Cartesian grid. The topography route follows a Cao2018-inspired workflow with preclassified boundary categories instead of per-step stress-zeroing patches.

4. Source and Receiver Setup

The source is injected as a delayed plane-stress excitation with user-controlled incident dip and azimuth. Receivers are extracted along the surface centerline, which keeps the acquisition geometry simple and comparable across cases.

5. Compute and Postprocess Pipeline

The compute stage writes raw arrays and metadata under output/. The postprocess stage then produces relief-aware wavefield GIFs and centerline seismograms without requiring extra manual plotting steps.

Quick Start

1) Install dependencies

python -m pip install -r requirements.txt

2) Run a lightweight smoke case

python scripts/run_acceptance_case.py --case flat --width-x-km 2 --width-y-km 2 --depth-km 1.5 --dx-m 250 --dy-m 250 --dz-m 250 --tmax-s 1.5 --n-snapshots 6 --output-tag smoke

3) Run the flat two-layer gallery case

python scripts/run_acceptance_case.py --case flat --width-x-km 30 --width-y-km 30 --depth-km 30 --dx-m 500 --dy-m 500 --dz-m 500 --layer-interface-depth-km 15 --source-depth-km 22 --n-snapshots 30

4) Run the XY-topography two-layer gallery case

python scripts/run_acceptance_case.py --case topography_xy --width-x-km 30 --width-y-km 30 --depth-km 30 --dx-m 500 --dy-m 500 --dz-m 500 --layer-interface-depth-km 15 --source-depth-km 22 --f0-hz 0.3 --tmax-s 60 --n-snapshots 40

Outputs are written under output/.

Repository Structure

• src/telefd3d/: core configuration, model construction, CPML, solver, wavelet, and postprocess modules.
• scripts/run_acceptance_case.py: main CLI entry for acceptance and gallery runs.
• assets/demo/: lightweight media assets used by the README gallery.
• output/: local run artifacts and metadata, ignored by git.

References

1. Graves, R. W. (1996). Simulating Seismic Wave Propagation in 3D Elastic Media Using Staggered-Grid Finite Differences. Bulletin of the Seismological Society of America, 86(4), 1091-1106.
2. Komatitsch, D., and Martin, R. (2007). An unsplit convolutional perfectly matched layer improved at grazing incidence for the seismic wave equation. Geophysics, 72(5), SM155-SM167. https://doi.org/10.1190/1.2757586
3. Cao, J., and Chen, J.-B. (2018). A parameter-modified method for implementing surface topography in elastic-wave finite-difference modeling. Geophysics, 83(6), T313-T332. https://doi.org/10.1190/GEO2018-0098.1

License

This project is licensed under the MIT License. See LICENSE.