Instaseis: Instant Global Seismograms Based on a Broadband Waveform Database¶

Instaseis calculates broadband seismograms from Green’s function databases generated with AxiSEM and allows for near instantaneous (on the order of milliseconds) extraction of seismograms. Using the 2.5D axisymmetric spectral element method, the generation of these databases, based on reciprocity of the Green’s functions, is very efficient and is approximately half as expensive as a single AxiSEM forward run. Thus this enables the computation of full databases at half the cost of the computation of seismograms for a single source in the previous scheme and hence allows to compute databases at the highest frequencies globally observed. By storing the basis coefficients of the numerical scheme (Lagrange polynomials), the Green’s functions are 4th order accurate in space and the spatial discretization respects discontinuities in the velocity model exactly. On top, AxiSEM allows to include 2D structure in the source receiver plane and readily includes other planets such as Mars.

For more information, please read our paper:

van Driel, M., Krischer, L., Stähler, S. C., Hosseini, K., and Nissen-Meyer, T. (2015).
Instaseis: instant global seismograms based on a broadband waveform database
Solid Earth, 6, 701-717
http://dx.doi.org/10.5194/se-6-701-2015

Syngine - Instaseis databases hosted by the IRIS DMC¶

Please note that the IRIS DMC hosts a large collection of Instaseis databases that also supports the dynamic extraction of seismograms. Thus no database must actually reside on your PC - Syngine will extract them for you and send the resulting seismograms over HTTP. Additionally Syngine can be used as a database backend from within Instaseis.

Syngine Product Page: http://ds.iris.edu/ds/products/syngine/
Syngine Documentation: http://service.iris.edu/irisws/syngine/1

There is also a paper for this:

Krischer, L., Hutko, A. R., Driel, M. van, Stähler, S., Trabant, C., and Nissen-Meyer, T. (2017).
On-demand custom broadband synthetic seismograms.
Seismological Research Letters, 88(4)
https://doi.org/10.1785/0220160210

Videos¶

This section shows two videos about Instaseis. One is a webinar hosted by CIG giving an introduction to AxiSEM and Instaseis. The second one is a quick demo of Instaseis' GUI.

Webinar
GUI Teaser

This video is a one hour long webinar hosted by CIG containing an introduction to AxiSEM and Instaseis. It explains the basic concepts behind both and additional demonstrates how to calculate databases with AxiSEM and how to use Instaseis at a basic level.

Get a first impression of the things Instaseis can do by taking a short video tour of our graphical user interface (:ref:`gui-label`). Make sure to watch it in HD!

Contact Us¶

If you encounter a bug or another error, please open a new issue on Github. For generic questions and to stay up to date with Instaseis, please use our mailing list. Send an email to it via instaseis@googlegroups.com and subscribe by sending an email to instaseis+subscribe@googlegroups.com.

Changelog¶

The most recent changelog can always be found here.

Installation¶

Installation using conda-forge

By far the easiest way to install Instaseis is to download Anaconda/Miniconda, install it and then run

$ conda install -c conda-forge instaseis

This will download and install Instaseis including all its dependencies. For other options, please keep on reading.

Requirements¶

Instaseis is implemented as a Python library and has a number of dependencies listed here. It might well work with other versions but only the versions listed here are continuously tested and supported. Instaseis currently runs on Linux and Mac OS X. Adding support for Windows is mainly a question of compiling the shared Fortran librarys - pull requests are welcome.

gfortran >= 4.7
Python >= 3.7
ObsPy >= 1.2.1
h5py
requests
tornado
jsonschema >= 2.4
geographiclib

To run the tests, please also install:

flake8
pytest
pytest-xdist
responses

The optional graphical user interface furthermore requires

PySide2
pyqtgraph (Must at least be version 0.11 - at the time of writing this means installing the dev version with pip install https://github.com/pyqtgraph/pyqtgraph/archive/develop.zip)
matplotlib
basemap
pillow

Fortran Compiler¶

If you don’t have gfortran, please install it (on Linux) with

$ sudo apt-get install gfortran

or the equivalent of your distribution. On OSX we recommend to install Homebrew and then use it to install gfortran:

$ brew install gcc

Python and Dependencies¶

If you know what you are doing, just make sure the aforementioned dependencies are installed. Otherwise do yourself a favor and download the Anaconda Python distribution. It is a free scientific Python distribution bundling almost all necessary modules with a convenient installer (does not require root access!). Once installed assert that pip and conda point to the Anaconda installation folder (you may need to open a new terminal after installing Anaconda).

$ conda install -c conda-forge obspy h5py requests tornado flake8 pytest mock basemap pyqt pip jsonschema responses pyqtgraph pytest-xdist

A possible complication arises if you are running on a server without a display. In that case please edit (on Linux) ~/.config/matplotlib/matplotlibrc (create if it does not exist) and make sure the following line is part of it:

backend: agg

A fairly recent development is that conda, on some systems, ships libgfortran3 versions incompatible with the system libraries. If you see errors like:

ImportError:
/home/travis/miniconda/lib/python2.7/site-packages/scipy/special/../../../../libgfortran.so.3:
version `GFORTRAN_1.4' not found

please try the following:

$ conda remove libgfortran --force

and if that results in some other issues (try it first!), also execute:

$ conda install libgcc --force

Installing Instaseis¶

User Installation¶

After the prerequisites are fulfilled, installation of the latest stable Instaseis version is as easy as:

$ pip install instaseis

Developer Installation¶

Clone the git repository and install in an editable fashion.

$ git clone https://github.com/krischer/instaseis.git
$ cd instaseis
$ pip install -v -e .

Testing¶

Many test run without these two packages, but executing the full test suite requires two additional packages: click and netcdf4. If you don’t already have them, install with

$ conda install click netcdf4

To assert that your installation is working properly, execute

$ python -m instaseis.tests

and make sure all tests pass. Otherwise please contact the developers. To speed up the tests they can also be run in parallel with (n is the number of cores):

$ cd /path/to/instaseis
$ py.test -n 4

Build the Documentation¶

The documentation requires sphinx and the Bootstrap theme. Install both with

$ pip install sphinx sphinx-bootstrap-theme

Build the doc with

$ cd doc
$ make html

Finally open the doc/_build/html/index.html file with the browser of your choice.

Tutorial¶

Learning Python and ObsPy¶

Instaseis is written in Python and utilizes the data structures of ObsPy to allow the construction of modern and efficient workflows. Python is an easy to learn and powerful interactive programming language with an exhaustive scientific ecosystem. The following resources are useful if you are starting out with Python and ObsPy:

Acquiring A Database¶

To use Instaseis, one requires access to a waveform database. AxiSEM has to be used to calculate one from scratch. As these database tend to get very big we so far cannot offer them as a download. If you are interested in a big database, please contact us.

To quickly get started, please download one of these low frequency example databases (please note that they may only be available temporarily):

PREM 20 seconds dominant period (581 MB)
PREM 10 seconds dominant period (3.4 GB)

Using Instaseis¶

To use Instaseis you first have to open a connection to an Instaseis database. Instaseis supports connections to local and remote Green’s function databases; a local database consists of up to four NetCDF files on the filesystem whereas a remote database requires an Instaseis server answering queries. The usage and capabilities of both are completely equivalent. This section deals with using Instaseis to generate seismograms; if you wish to run an Instaseis server, please see the documentation of the Instaseis Server.

Connecting to either a local or a remote Instaseis database happens with the open_db() function. It will return either an InstaseisDB or a RemoteInstaseisDB object. Additional arguments and keyword arguments are passed to the the initialization function of these objects. Once the database objects are created, usage of both is identical. Be aware that the initialization of the database objects is potentially a fairly expensive operation so make sure to do it only when necessary (usually once per database).

Note

If opening a local database and the ordered_output.nc4 files are located for example in /path/to/DB/PZ/Data and /path/to/DB/PX/Data, please pass /path/to/DB to the open_db() function. Instaseis will recursively search the child directories for the necessary files and open them.

>>> import instaseis

>>> # Open connection to a local database by giving the path on disc where
>>> # the `ordered_output.nc4` files of AxiSEM are stored.
>>> db = instaseis.open_db("/path/to/10s_PREM")

>>> # Or open connection to a remote database by giving an HTTP URL.
>>> db = instaseis.open_db("http://123.456.789.123:1234")

>>> # Get some basic information by printing the database object.
>>> print(db)
RemoteInstaseisDB reciprocal Green's function Database (v7) generated with these parameters:
components           : vertical and horizontal
velocity model       : prem_ani
attenuation          : True
dominant period      : 10.000 s
dump type            : displ_only
excitation type      : dipole
time step            : 2.436 s
sampling rate        : 0.411 Hz
number of samples    : 739
seismogram length    : 1797.7 s
source time function : errorf
source shift         : 17.051 s
spatial order        : 4
min/max radius       : 5700.0 - 6371.0 km
Planet radius        : 6371.0 km
min/max distance     : 0.0 - 180.0 deg
time stepping scheme : newmark2
compiler/user        : gfortran 4.9.1 by lion on Laptop
directory/url        : http://123.456.789.123:1234
size of netCDF files : 3.4 GB
generated by AxiSEM version 60945ec at 2014-10-23T21:32:58.000000Z

The get_seismograms() method is called to generate seismograms as Stream objects with the waveform data. This enables easy serialization in a large selection of formats and facilitates post processing by utilizing ObsPy.

To generate seismograms source information must be given either as a Source object, a ForceSource object, or as a FiniteSource object. Receiver information must be passed in form of a Receiver object. Please refer to the documentation of these classes for more details.

>>> import obspy
>>> receiver = instaseis.Receiver(
...     latitude=42.6390, longitude=74.4940, network="AB", station="CED")
>>> source = instaseis.Source(
...     latitude=89.91, longitude=0.0, depth_in_m=12000,
...     m_rr = 4.710000e+24 / 1E7,
...     m_tt = 3.810000e+22 / 1E7,
...     m_pp =-4.740000e+24 / 1E7,
...     m_rt = 3.990000e+23 / 1E7,
...     m_rp =-8.050000e+23 / 1E7,
...     m_tp =-1.230000e+24 / 1E7,
...     origin_time=obspy.UTCDateTime(2011, 1, 2, 3, 4, 5))
>>> st = db.get_seismograms(source=source, receiver=receiver)
>>> print(st)
3 Trace(s) in Stream:
AB.CED..MXZ | 2011-01-02T03:04:05Z - ... | 0.4 Hz, 732 samples
AB.CED..MXN | 2011-01-02T03:04:05Z - ... | 0.4 Hz, 732 samples
AB.CED..MXE | 2011-01-02T03:04:05Z - ... | 0.4 Hz, 732 samples

Source and receiver can also be replaced by ObsPy objects. This can be used to calculate synthetics based on standard file formats and web services.

>>> # Read event information from a local QuakeML file.
>>> cat = obspy.readEvents("quake.xml")
>>> print(cat)
1 Event(s) in Catalog:
2010-03-11T06:22:20.100000Z | -57.460,  -27.580 | 5.6 Mwc

>>> # Query a web service for station information.
>>> from obspy.fdsn import Client
>>> c = Client("IRIS")
>>> inv = c.get_stations(network="IU", station="ANMO", level="station",
...                      starttime=cat[0].origins[0].time)
>>> print(inv)
Created by: IRIS WEB SERVICE: fdsnws-station | ...
Contains:
    Networks (1): IU
    Stations (1): IU.ANMO (Albuquerque, New Mexico, USA)

>>> st = db.get_seismograms(source=cat, receiver=inv)
>>> print(st)
3 Trace(s) in Stream:
IU.ANMO..MXZ | 2010-03-11T06:22:20Z - ... | 0.4 Hz, 732 samples
IU.ANMO..MXN | 2010-03-11T06:22:20Z - ... | 0.4 Hz, 732 samples
IU.ANMO..MXE | 2010-03-11T06:22:20Z - ... | 0.4 Hz, 732 samples

GUI¶

Instaseis contains an optional graphical user interface which is useful to explore a database and for educational purposes. To launch it just type

$ python -m instaseis.gui

Screenshot of the Instaseis graphical user interface (GUI). Aside from quickly exploring the characteristics of a given Green’s function database it is a great tool for understanding and teaching many aspect of seismograms. The speed of Instaseis enables an immediate visual response to changing source and receiver parameters. The left hand side shows three component seismograms where theoretical arrival times of various seismic phases are overlaid as vertical lines. The bar at the top is used to change filter and resampling settings and the section on the right side is used to modify source and receiver parameters.

Acknowledgements¶

We gratefully acknowledge support from the European Commission (Marie Curie Actions, ITN QUEST, www.quest-itn.org) and the EU-FP7 725 690 VERCE project (number 283543, www.verce.eu).