disba

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

| Class | Purpose | |-------|---------| | PhaseDispersion | Phase velocity dispersion curves | | GroupDispersion | Group velocity dispersion curves | | PhaseSensitivity | Sensitivity kernels (dc/dVs, dc/dVp, dc/drho) |

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

| Parameter | Unit | Description | |-----------|------|-------------| | thickness | km | Layer thickness (0 = half-space) | | vp | km/s | P-wave velocity | | vs | km/s | S-wave velocity | | rho | g/cm3 | Density |

Wave Types

| Type | Motion | Sensitivity | |------|--------|-------------| | Rayleigh | Vertical + radial | Vs (primary), Vp (secondary) | | Love | Horizontal (SH) | Vs only |

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

| Tool | Best For | |------|----------| | disba | Fast dispersion computation, Numba-accelerated, Python-native | | CPS (Herrmann) | Full surface wave analysis suite, Fortran-based, broader features | | pysurf | Surface wave processing from field data, MASW/SASW workflows |

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

| Issue | Solution | |-------|----------| | No dispersion at short periods | Increase model resolution (thinner layers) | | Higher mode not computed | Mode may not exist at those periods | | Slow first run | Normal - Numba compiles on first call | | NaN in results | Check model validity (Vs < Vp, positive values) |

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