seisgo.dispersion

The dispersion module extracts group/phase velocity dispersion images from seismic waveform gathers and computes synthetic dispersion curves via forward modeling.

Note

This module is actively developed. Some functions may be extended in future releases.

seisgo.dispersion.forward_solver(vs, periods, thickness, wave_type='rayleigh', mode=1, velocity_type='group')[source]

Wrapper for surf96 to compute synthetic group velocity dispersion curve. Maps Vs to Vp and Density using standard geophysical relations.

==PARAMETERS== vs: Vs for each layer in km/s. periods: periods in s. thickness: layer thickness in 1-d array in km. wave_type: rayleigh or love. mode: wave mode. default 1 (fundamental mode). velocity_type: group or phase. default group.

==RETURN== output of surf96 program. see manual of surf96 for details.

seisgo.dispersion.get_dispersion_image(g, t, d, pmin, pmax, vmin, vmax, dp=1, dv=0.1, window=1, pscale='ln', pband_extend=5, verbose=False, min_trace=5, min_wavelength=1.5, energy_type='power_sum', get_best_v=False, plot=False, figsize=None, cmap='jet', clim=[0, 1])[source]

Uses phase-shift method. Park et al. (1998): http://www.masw.com/files/DispersionImaingScheme-1.pdf

=====PARAMETERS==== g: waveform gather for all distances (traces). It should be a numpy array. t: time vector. d: distance vector corresponding to the waveforms in g pmin: minimum period. pmax: maximum period. vmin: minimum phase velocity to search. vmax: maximum phase velocity to search. dp: period increment. default is 1. dv: velocity increment in searching. default is 0.1 window: number of wavelength when slicing the time segments in computing summed energy. default is 1.

Window can be a two-element array [min,max], when the window size will be interpolated between the minimum and the maximum.

pscale: period vector scale in applying narrowband filters. default is ‘ln’ for linear scale. pband_extend: number of period increments to extend in filtering. defult is 5. verbose: verbose mode. default False. min_trace: minimum trace to consider. default 5. min_wavelength: minimum wavelength to satisfy far-field. default 1.5. energy_type: method to compute maximum energy, ‘envelope’ or ‘power_sum’. Default is ‘power_sum’ get_best_v: pick best velocity for each period. Default False. plot: plot dispersion image or not. Default is False. figsize: specify figsize. Decides automatically if not specified. cmap: colormap. Default is ‘jet’ clim: color value limit. Default is [0,1]

=====RETURNS==== dout: dispersion information showing the normalized energy for each velocity value for each frequency. vout: velocity vector used in searching. pout: period vector. best_v: best velocity (group velocity). Only return if get_best_v is True.

seisgo.dispersion.get_dispersion_waveforms_cwt(d, dt, fmin, fmax, dj=0.08333333333333333, s0=-1, J=-1, wvn='morlet')[source]

Produce dispersion wavefroms with continuous wavelet tranform.

===parameters=== d: 1-d array data. df: time interval. fmin, fmax: frequency range. dj=1/12, s0=-1, J=-1, wvn=’morlet’: pycwt.cwt parameters.

==returns=== dout, fout: narrowband-filtered waveforms and the frequency vector.

seisgo.dispersion.inversion(periods, velocity, thickness, initial_vs, iterations=8, damp=0.1, smooth=0.5, wave_type='rayleigh', mode=1, velocity_type='group', maxdv=0.02)[source]

Performs 1-D damped least-squares inversion with smoothness.

==PARAMETER== periods: wave periods in 1-d array velocity: observed velocity from disperson analysis in km/s. thickness: layer thickness in 1-d array in km. initial_vs: stating Vs for each layer. iterations: maximum number of iterations. default 8. damp: Damping (stability). default 0.1. smooth: Smoothness (geological plausibility). default 0.5. maxdv: maximum velocity perturbation in km/s.

==RETURN== vs_curr: inverted velocity for each layer.

seisgo.dispersion.narrowband_waveforms(d, dt, pmin, pmax, dp=1, pscale='ln', extend=10)[source]

Produce dispersion wavefroms with narrowband filters.

===parameters=== d: 1-d array data. dt: sampling interval. pmin, pmax: period range. dp: period increment in seconds. default 1 s. pscale: period scales. “ln” for linear [default]. “nln” for non-linear scale. extend: extend individual period value to form a band range. default: 5 scale steps.

==returns=== dout, pout: narrowband-filtered waveforms and the period vector.

Function Summary

`seisgo.dispersion.get_dispersion_image`	Uses phase-shift method.
`seisgo.dispersion.narrowband_waveforms`	Produce dispersion wavefroms with narrowband filters.
`seisgo.dispersion.get_dispersion_waveforms_cwt`	Produce dispersion wavefroms with continuous wavelet tranform.
`seisgo.dispersion.forward_solver`	Wrapper for surf96 to compute synthetic group velocity dispersion curve.

`get_dispersion_image` Parameter Reference

Parameter	Default	Description
`g`	required	2-D waveform gather, shape `(n_traces, n_samples)`.
`t`	required	Time vector (s). May be two-sided (negative to positive) or one-sided.
`d`	required	Distance vector (km), one value per trace row.
`pmin`, `pmax`	required	Period range (s).
`vmin`, `vmax`	required	Velocity search range (km/s).
`dp`	`1`	Period increment (s).
`dv`	`0.1`	Velocity grid spacing (km/s).
`window`	`1`	Number of wavelengths for the travel-time extraction window. Can be a 2-element list `[min, max]` for period-dependent window size.
`pscale`	`"ln"`	Period sampling: `"ln"` (linear) or `"nln"` (logarithmic).
`pband_extend`	`5`	Number of extra period steps used when constructing narrowband filters.
`min_trace`	`5`	Minimum number of traces satisfying the far-field criterion.
`min_wavelength`	`1.5`	Minimum source–receiver distance expressed in wavelengths.
`energy_type`	`"power_sum"`	Energy measure: `"power_sum"` or `"envelope"`.
`get_best_v`	`False`	If `True`, also return the peak-energy velocity per period.
`plot`	`False`	Display dispersion image immediately.

Return values

When the time vector is two-sided (side = "a"):

dimage, vout, pout = get_dispersion_image(...)
# dimage.shape == (2, n_periods, n_velocities)
# index 0 = negative lag, index 1 = positive lag

When get_best_v=True, a fourth return value best_v is appended.

`forward_solver` Reference

Wraps surf96 (from pysurf96) to compute Rayleigh or Love wave group/phase velocity dispersion curves for a layered Earth model.

Parameter	Default	Description
`vs`	required	Vs for each layer (km/s), from surface to half-space.
`periods`	required	Target periods (s).
`thickness`	required	Layer thicknesses (km). The last element should be `0` (half-space).
`wave_type`	`"rayleigh"`	`"rayleigh"` or `"love"`.
`mode`	`1`	Mode number (1 = fundamental mode).
`velocity_type`	`"group"`	`"group"` or `"phase"`.

Internal mapping (Vs → Vp and density):

Vp/Vs = √3
Density via Birch’s law: ρ = 0.32·Vp + 0.77

from seisgo import dispersion
import numpy as np

vs        = np.array([2.0, 3.0, 3.8, 4.2])
thickness = np.array([8.0, 12.0, 20.0, 0.0])
periods   = np.arange(5, 40, 2)

gv = dispersion.forward_solver(vs, periods, thickness,
                               wave_type="rayleigh", velocity_type="group")