mtuq.WaveformMisfit

class mtuq.WaveformMisfit(norm='hybrid', time_shift_groups=['ZRT'], time_shift_min=0.0, time_shift_max=0.0, level=2, normalize=True, verbose=2)[source]

Bases: object

Waveform misfit function

Evaluates misfit between data and synthetics using time shifts followed by waveform differences. This approach, due to Zhao1994 and Zhu1996, has become widely used in regional seismology. See docs/references for more information.

Usage

Evaluating misfit is a two-step procedure.

First, the user supplies parameters such as the type of norm (see below for detailed argument descriptions):

misfit = Misfit(**parameters)

Second, the user supplies data, Green’s functions, and sources:

values = misfit(data, greens, sources)

During misfit evaluation, synthetics are then generated and compared with data, and a NumPy array of misfit values is returned of the same length as sources.

Parameters

norm (str)

  • 'L2': conventional L2 norm (fast)

  • 'L1': conventional L1 norm (slow)

  • 'hybrid': hybrid L1-L2 norm (much faster than L1 but still robust)

level (int): optimization level (see further details below)

time_shift_groups (list)

  • ['ZRT']: forces all three components to have the same time shift

  • ['ZR','T']: forces vertical and radial components to have the same time shift, while transverse time shift is allowed to vary independently

  • ['Z','R','T']: allows time shifts of all three components to vary independently

time_shift_min (float): minimum allowable time shift (s)

time_shift_max (float): maximum allowable time shift (s)

Note

Convention : A positive time shift means synthetics are arriving too early and need to be shifted forward in time to match the observed data.

Optimization Levels

Because waveform misfit evaluation is the most computationally expensive task, we have implemented three different versions:

  • a readable pure Python version (mtuq.misfit.level0)

  • a fast pure Python version (mtuq.misfit.level1)

  • a very fast numba version (mtuq.misfit.level2)

  • a very fast Cython version (mtuq.misfit.level3)

While having exactly the same input argument syntax, the following versions differ in the following ways:

  • level=0 provides a reference for understanding what the code is doing and for checking the correctness of the fast implementations

  • level=1 is an optimized pure Python implementation which provides significant computational savings for len(sources) > 100. This version is the closest to Zhu1996’s original C software.

  • level=2 is an optimized numba implementation, in which a Python wrapper is used to combine ObsPy traces into multidimensional arrays. These arrays are passed to a numba routine, which does the main computational work. Unlike the previous two versions, this implementation requires that all ObsPy traces have the same time discretization.

  • level=3 is an optimized Cython implementation, in which a Python wrapper is used to combine ObsPy traces into multidimensional arrays. These arrays are passed to a Cython routine, which does the main computational work. This implementation also requires that all ObsPy traces have the same time discretization.

Note

Cython extension modules are no longer automatically compiled during installation, but can be manually compiled via build_ext.sh.

Public Methods

collect_attributes

Collects misfit, time shifts and other attributes corresponding to each trace

collect_synthetics

Collects synthetics with misfit, time shifts and other attributes attached

description