Skip to content
Teleseismic body wave modeling
Jupyter Notebook Python Fortran TeX
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

Telewavesim: Software for teleseismic body wave modeling

The structure of the Earth's crust and upper mantle gives useful information on the internal composition and dynamics of our planet. Some of the most widely used techniques to infer these properties are based on examining the effect of teleseismic body wave (i.e., P and S waves that originate from distant earthquakes and arrive as plane waves) propagation (e.g., transmission and scattering) through stratified media. Modeling the seismic response from stacks of subsurface layers is therefore an essential tool in characterizing their effect on observed seismograms.

This package contains python and fortran modules to synthesize teleseismic body-wave propagation through stacks of generally anisotropic and strictly horizontal layers using the matrix propagator approach of Kennett (1983), as implemented in Thomson (1997). The software also properly models reverberations from an overlying column of water using the R/T matrix expressions of Bostock and Trehu (2012), effectively simulating ocean-bottom seismic (OBS) station recordings. The software will be useful in a variety of teleseismic receiver-based studies, such as P or S receiver functions, long-period P-wave polarization, shear-wave splitting from core-refracted shear waves (i.e., SKS, SKKS), etc. It may also be the starting point for stochastic inverse methods (e.g., Monte Carlo sampling). The main part of the code is written in fortran with python wrappers. Common computational workflows are covered in the Jupyter notebooks bundled with this package.

DOI PyPI version build status codecov



The current version was developed using Python3.7 Also, the following packages are required:

By default, both numpy and matplotlib are installed as dependencies of obspy.

Conda environment

We recommend creating a custom conda environment where telewavesim can be installed along with its dependencies:

conda create -n tws python=3.7 obspy -c conda-forge

Activate the newly created environment:

conda activate tws

Installing from source

  • Download or clone the repository:
git clone
cd Telewavesim
  • Install using pip:
pip install .

Installing from Pypi

pip install telewavesim

Possible installation pitfalls with conda

Using conda it might be necessary to use the fortran comiler provided with conda-forge. Add gfortran_osx-64 or gfortran_linux-64 package to the above conda calls. On Linux it might further be necessary to install the lapack conda package.


API Documentation

The API for all functions in telewavesim can be accessed from

Jupyter Notebooks

Included in this package is a set of Jupyter Notebooks, which give examples on how to call the various routines and obtain plane wave seismograms and receiver functions. The Notebooks describe how to reproduce published examples of synthetic data from Audet (2016) and Porter et al. (2011).

After installing telewaveim, these notebooks can be locally installed (i.e., in a local folder Notebooks) from the package by running:

from telewavesim import doc

To run the notebooks you will have to further install jupyter:

conda install jupyter

Then cd Notebooks and type:

jupyter notebook

You can then save the notebooks as python scripts, check out the model files and you should be good to go!

Setting up new models

To set up the models, install the Jupyter notebooks and check out the examples in the models folder, or visit the wiki page for telewavesim.


A series of tests are located in the tests subdirectory. In order to perform these tests, run pytest (conda install pytest if needed):

pytest -v --pyargs telewavesim


  • Audet, P. (2016). Receiver functions using OBS data: promises and limitations from numerical modelling and examples from the Cascadia Initiative. Geophysical Journal International, 205, 1740-1755.

  • Bostock, M.G., and Trehu, A.M. (2012). Wave-field decomposition of ocean-bottom seismograms. Bulletin of the Seismological Society of America, 102, 1681-1692.

  • Kennett, B.L.N. (1983). Seismic wave propagation in stratified media. Cambridge University Press, 342pp.

  • Porter, R., Zandt, G., & McQuarrie, N. (2011). Pervasive lower-crustal seismic anisotropy in Southern California: Evidence for underplated schists and active tectonics. Lithosphere, 3(3), 201-220.

  • Thomson, C.J. (1997). Modelling surface waves in anisotropic structures: I. Theory. Physics of the Earth and Planetary interiors, 103, 195-206.

You can’t perform that action at this time.