mtuq.WaveformMisfit

class mtuq.WaveformMisfit(norm='hybrid', time_shift_groups=['ZRT'], time_shift_min=0.0, time_shift_max=0.0, optimization_level=2)

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)

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)

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

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 Python/C version (mtuq.misfit.level2)

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

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

• level1 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.

• level2 is an optimized Python/C implementation, in which a Python wrapper is used to combine ObsPy traces into multidimensional arrays. These arrays are passed to a C extension module, which does the main computational work. Unlike the other two versions, this implementation requires that all ObsPy traces have the same time discretization.

Note

During installation, C extension modules are automatically compiled by build_ext.sh using compiler flags given in setup.py. For performance tuning or compiler troubleshooting, users may wish to modify the get_compiler_args function in setup.py.

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