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
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)
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 firstname.lastname@example.org and subscribe by sending an email to email@example.com.
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.
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
jsonschema >= 2.4
To run the tests, please also install:
The optional graphical user interface furthermore requires
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)
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
$ 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
conda point to the Anaconda
installation folder (you may need to open a new terminal after installing
$ 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:
A fairly recent development is that
conda, on some systems, ships
libgfortran3 versions incompatible with the system libraries. If you see
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
After the prerequisites are fulfilled, installation of the latest stable Instaseis version is as easy as:
$ pip install instaseis
Clone the git repository and install in an editable fashion.
$ git clone https://github.com/krischer/instaseis.git $ cd instaseis $ pip install -v -e .
Many test run without these two packages, but executing the full test suite
requires two additional packages:
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
$ 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
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):
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).
If opening a local database and the
ordered_output.nc4 files are
located for example in
/path/to/DB to the
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
method is called to generate seismograms as
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.origins.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
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.
- Main Instaseis Classes
- Sources and Receivers
- Utility Functions
- Instaseis Server
- Advanced Server Configuration
- Database Layout and Repacking