disba

name: disba description: | Compute surface wave dispersion curves for layered Earth models using the Thomson-Haskell matrix method with Numba acceleration. Use when Claude needs to: (1) Calculate Rayleigh or Love wave phase velocities, (2) Compute group velocity dispersion, (3) Generate sensitivity kernels for inversion, (4) Forward model dispersion curves from velocity profiles, (5) Compare dispersion between different Earth models, (6) Set up surface wave tomography workflows. version: 1.0.0 author: Geoscience Skills license: MIT tags: [Surface Waves, Dispersion, Rayleigh, Love, Seismology, Disba, Phase Velocity, Group Velocity] dependencies: [disba>=0.5.0, numpy, numba] complements: [obspy, segyio] workflow_role: analysis

disba - Surface Wave Dispersion

Quick Reference

import numpy as np
from disba import PhaseDispersion, GroupDispersion

# Define velocity model (thickness, Vp, Vs, density)
# thickness in km, velocities in km/s, density in g/cm3
thickness = np.array([0.5, 1.0, 2.0, 0.0])  # 0.0 = half-space
vp = np.array([1.5, 2.5, 4.0, 6.0])
vs = np.array([0.8, 1.4, 2.3, 3.5])
rho = np.array([1.8, 2.0, 2.3, 2.6])

# Periods to compute (seconds)
periods = np.linspace(0.1, 5.0, 50)

# Calculate Rayleigh wave phase velocity
pd = PhaseDispersion(*zip(thickness, vp, vs, rho))
cpr = pd(periods, mode=0, wave='rayleigh')  # Fundamental mode

# Calculate group velocity
gd = GroupDispersion(*zip(thickness, vp, vs, rho))
ugr = gd(periods, mode=0, wave='rayleigh')

Key Classes

Essential Operations

Rayleigh and Love Waves

pd = PhaseDispersion(*zip(thickness, vp, vs, rho))
cpr = pd(periods, mode=0, wave='rayleigh')  # Vertical + radial motion
cpl = pd(periods, mode=0, wave='love')       # Horizontal SH motion

Multiple Modes

for mode in range(3):  # Fundamental + higher modes
    try:
        cpr = pd(periods, mode=mode, wave='rayleigh')
    except Exception:
        pass  # Higher modes may not exist at all periods

Sensitivity Kernels

from disba import PhaseSensitivity

ps = PhaseSensitivity(*zip(thickness, vp, vs, rho))
kernel_vs = ps(period=1.0, mode=0, wave='rayleigh', parameter='velocity_s')
# Other parameters: 'velocity_p', 'density'

Forward Modelling

def forward_model(vs_profile, thickness, vp_vs_ratio=1.73):
    """Compute dispersion curve from Vs profile."""
    vp = vs_profile * vp_vs_ratio
    rho = 0.32 * vp + 0.77  # Gardner relation
    pd = PhaseDispersion(*zip(thickness, vp, vs_profile, rho))
    return pd(periods, mode=0, wave='rayleigh')

Model Parameters

Wave Types

Key Points

1. Last layer thickness = 0 indicates half-space (infinite depth)
2. Numba JIT - First call is slower due to compilation
3. Higher modes may not exist at all periods
4. Sensitivity kernels show which depths affect each period

When to Use vs Alternatives

Use disba when you need fast forward modelling of dispersion curves for inversion or parameter studies. Numba acceleration makes it ideal for iterative workflows requiring thousands of forward computations.

Use CPS instead when you need the full Herrmann suite: receiver functions, synthetic seismograms, or established research-grade tools.

Use pysurf instead when processing raw field data (shot gathers) through MASW/SASW workflows to extract dispersion curves from measured data.

Common Workflows

Compute and analyze dispersion curves

- [ ] Define layered velocity model (thickness, Vp, Vs, density)
- [ ] Set last layer thickness to 0.0 (half-space)
- [ ] Choose period range appropriate for model depth
- [ ] Compute phase/group velocity for fundamental mode
- [ ] Compute higher modes if needed (wrap in try/except)
- [ ] Generate sensitivity kernels to assess depth resolution
- [ ] Compare computed curves against observed data

Common Issues

References

• Dispersion Curves - Phase vs group velocity, mode numbering
• Velocity Models - Model setup, units, common profiles

Scripts

• scripts/dispersion_analysis.py - Compute and plot dispersion curves