Pyadjoint

Pyadjoint is a Python package to measure misfits and calculate adjoint sources. It aims to provide a comprehensive package and incorporate various types of measurements and associated adjoint sources.

Installation

Pyadjoint utilizes ObsPy (and some of its dependencies) for the processing and data handling. As a first step, please follow the installation instructions of ObsPy for your given platform (we recommend the installation with Anaconda as it will most likely result in the least amount of problems). Pyadjoint should work with Python versions 2.7, 3.3, and 3.4 (mainly depends on the used ObsPy version). To install it, best use pip (not working yet!):

$ pip install pyadjoint

If you want the latest development version, or want to work on the code, you will have to install with the help of git.

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

Tests

To assure the installation is valid and everything works as expected, run the tests with

$ python -m pyadjoint.tests

Usage

Basic Usage

The first step is to import ObsPy and Pyadjoint.



In [ ]:

    
import obspy
import pyadjoint

Pyadjoint expects the data to be fully preprocessed thus both observed and synthetic data are expected to have exactly the same length, sampling rate, and spectral content. Pyadjoint furthermore does not care about the actual components in question; it will use two traces and calculate misfit values and adjoint sources for them. To provide a familiar nomenclature we will always talk about observed and synthetic data Pyadjoint is independent of what the data actually represents.



In [ ]:

    
# Helper function to get some example data used for
# illustrative purposes.
obs, syn = pyadjoint.utils.get_example_data()
# Select the vertical components of both.
obs = obs.select(component="Z")[0]
syn = syn.select(component="Z")[0]

Essentially all of ``Pyadjoint``'s functionality is accessed through its central :func:`~pyadjoint.adjoint_source.calculate_adjoint_source` function. A list of available adjoint source types can be found in :doc:`adjoint_sources/index`.



In [ ]:

    
adj_src = pyadjoint.calculate_adjoint_source(
    # The type of misfit measurement and adjoint source.
    adj_src_type="waveform_misfit",
    # Pass observed and synthetic data traces.
    observed=obs, synthetic=syn,
    # The spectral content of the data.
    min_period=20.0, max_period=100.0,
    # The window borders in seconds since the first sample.
    left_window_border=800.0,
    right_window_border=900.0)
print(adj_src)

It returns an :class:`~pyadjoint.adjoint_source.AdjointSource` object.



In [ ]:

    
# Access misfit and adjoint sources. The misfit is a floating point number.
print(adj_src.misfit)
# The adjoint source is a a numpy array.
print(adj_src.adjoint_source)

Usage Options

In case one just wants to calculate the misfit value, pass adjoint_src=False in which case the adjoint source will not be calculated. This sometimes is much faster and useful for line searches or similar endeavors.



In [ ]:

    
print(pyadjoint.calculate_adjoint_source(
    adj_src_type="waveform_misfit", observed=obs, synthetic=syn,
    min_period=20.0, max_period=100.0,
    left_window_border=800.0, right_window_border=900.0, adjoint_src=False))

All adjoint source types can also be plotted during the calculation. The type of plot produced depends on the type of misfit measurement and adjoint source.



In [ ]:

    
pyadjoint.calculate_adjoint_source(
    adj_src_type="waveform_misfit", observed=obs, synthetic=syn,
    min_period=20.0, max_period=100.0,
    left_window_border=800.0, right_window_border=900.0, plot=True);

Many types of adjoint sources have additional arguments that can be passed to it. The waveform misfit adjoint source for example allows to specifiy the width and type of the taper applied to the data. Please see the documentation of the different :doc:`adjoint_sources/index` for details.



In [ ]:

    
print(pyadjoint.calculate_adjoint_source(
    adj_src_type="waveform_misfit", observed=obs, synthetic=syn,
    min_period=20.0, max_period=100.0,
    left_window_border=800.0, right_window_border=900.0,
    taper_percentage=0.3, taper_type="cosine"))

Saving to Disc

One of course wants to serialize the calculated adjoint sources to disc at one point in time. You need to pass the filename and the desired format as well as some format specific parameters to the :meth:`~pyadjoint.adjoint_source.AdjointSource.write` method of the :class:`~pyadjoint.adjoint_source.AdjointSource` object. Instead of a filename you can also pass an open file or a file-like object. Please refer to its documentation for more details.



In [ ]:

    
adj_src.write(filename="NET.STA.CHA.adj_src",
              format="SPECFEM", time_offset=-10)



In [ ]:

    
!head NET.STA.CHA.adj_src
!rm NET.STA.CHA.adj_src

Detailed Documentation ---------------------- Further Pages ~~~~~~~~~~~~~ .. toctree:: :maxdepth: 2 adjoint_sources/index example_dataset citations how_to_add_a_new_adjoint_source API ~~~ .. toctree:: :maxdepth: 2 adjoint_source utils



In [ ]: