keurfonluu / disba

Numba-accelerated computation of surface wave dispersion

disba

disba is a computationally efficient Python library for the modeling of surface wave dispersion that implements a subset of codes from Computer Programs in Seismology (CPS) in Python compiled just-in-time with numba. Such implementation alleviates the usual prerequisite for a Fortran compiler needed by other libraries also based on CPS (e.g., pysurf96, srfpython and PyLayeredModel) which often leads to further installation troubleshooting, especially on Windows platform.

disba aims to be lightweight and portable without compromising on the performance. For both Rayleigh-wave and Love-wave, it is significantly faster than CPS's surf96 program compiled with f2py, noticeably for large number of layers.

Features

Forward modeling:

• Compute Rayleigh-wave phase or group dispersion curves using Dunkin's matrix or fast delta matrix algorithms,
• Compute Love-wave phase or group dispersion curves using Thomson-Haskell method,
• Compute Rayleigh-wave ellipticity.

Eigenfunctions and sensitivity kernels:

• Compute Rayleigh- and Love- wave eigenfunctions,
• Compute Rayleigh- and Love- wave phase or group velocity, and Rayleigh-wave ellipticity sensitivity kernels with respect to layer thickness, P- and S- wave velocities, and density.

Installation

The recommended way to install disba and all its dependencies is through the Python Package Index:

pip install disba[full] --user

Otherwise, clone and extract the package, then run from the package location:

pip install .[full] --user

To test the integrity of the installed package, check out this repository and run:

pytest

Documentation

Refer to the online documentation for detailed description of the API and examples.

Alternatively, the documentation can be built using Sphinx:

pip install -r doc/requirements.txt
sphinx-build -b html doc/source doc/build

Usage

The following example computes the Rayleigh- and Love- wave phase velocity dispersion curves for the 3 first modes.

import numpy as np
from disba import PhaseDispersion

# Velocity model
# thickness, Vp, Vs, density
# km, km/s, km/s, g/cm3
velocity_model = np.array([
   [10.0, 7.00, 3.50, 2.00],
   [10.0, 6.80, 3.40, 2.00],
   [10.0, 7.00, 3.50, 2.00],
   [10.0, 7.60, 3.80, 2.00],
   [10.0, 8.40, 4.20, 2.00],
   [10.0, 9.00, 4.50, 2.00],
   [10.0, 9.40, 4.70, 2.00],
   [10.0, 9.60, 4.80, 2.00],
   [10.0, 9.50, 4.75, 2.00],
])

# Periods must be sorted starting with low periods
t = np.logspace(0.0, 3.0, 100)

# Compute the 3 first Rayleigh- and Love- wave modal dispersion curves
# Fundamental mode corresponds to mode 0
pd = PhaseDispersion(*velocity_model.T)
cpr = [pd(t, mode=i, wave="rayleigh") for i in range(3)]
cpl = [pd(t, mode=i, wave="love") for i in range(3)]

# pd returns a namedtuple (period, velocity, mode, wave, type)

Likewise, GroupDispersion can be used for group velocity.

disba's API is consistent across all its classes which are initialized and called in the same fashion. Thus, eigenfunctions are calculated as follow:

from disba import EigenFunction

eigf = EigenFunction(*velocity_model.T)
eigr = eigf(20.0, mode=0, wave="rayleigh")
eigl = eigf(20.0, mode=0, wave="love")

# eigf returns a namedtuple
#  - (depth, ur, uz, tz, tr, period, mode) for Rayleigh-wave
#  - (depth, uu, tt, period, mode) for Love-wave

Phase velocity sensitivity kernels (GroupSensitivity for group velocity):

from disba import PhaseSensitivity

ps = PhaseSensitivity(*velocity_model.T)
parameters = ["thickness", "velocity_p", "velocity_s", "density"]
skr = [ps(20.0, mode=0, wave="rayleigh", parameter=parameter) for parameter in parameters]
skl = [ps(20.0, mode=0, wave="love", parameter=parameter) for parameter in parameters]

# ps returns a namedtuple (depth, kernel, period, velocity, mode,wave, type, parameter)

Ellipticity and ellipticity sensitivity kernels:

from disba import Ellipticity, EllipticitySensitivity

ell = Ellipticity(*velocity_model.T)
rel = ell(t, mode=0)

# ell returns a namedtuple (period, ellipticity, mode)

es = EllipticitySensitivity(*velocity_model.T)
ek = [es(20.0, mode=0, parameter=parameter) for parameter in parameters]

# es returns a namedtuple (depth, kernel, period, velocity, mode, wave, type, parameter)

Contributing

Please refer to the Contributing Guidelines to see how you can help. This project is released with a Code of Conduct which you agree to abide by when contributing.

disba's Issues

Citing needed

First, it´s great software!

Description of the desired feature

The problem is that I have no formal way to cite it in a publication! Please if you have a paper to reference about this package add it to the description/manual/wiki so the community can cite it. If not, you should publish your results!! Mainly becouse it's awesome for scientits that work on python.

Congrats for the soft!

Are you willing to help implement and maintain this feature? Yes/No

Adding physical dispersion correction induced by seismic attenuation

Thank you for developing a user-friendly software for surface wave tomography.

Can we add the physical dispersion correction into the software, which is significant for the long period surface waves sensitive to mantle structure? The formulation is described by Kanamori's paper.

velocity model problem

Description of the problem
The sample file is correct，when I adjust the velocity model, there will be an error message “disba._exception.DispersionError: failed to find root for fundamental mode”.

Full code that generated the error

import numpy
from disba import PhaseDispersion
import  matplotlib.pyplot as plt


# Velocity model  # todo : model settle
# thickness, Vp, Vs, density
# km, km/s, km/s, g/cm3
velocity_model = numpy.array([ # model change
   [3.0, 7.00, 3.50, 2.00],
   [5.0, 6.80, 3.40, 2.00],
   [4.0, 7.00, 3.50, 2.00],
   [10.0, 7.60, 3.80, 2.00],
   [10.0, 8.40, 4.20, 2.00],
   [10.0, 9.00, 4.50, 2.00],
])

# Periods must be sorted starting with low periods
t = numpy.logspace(0.0, 3.0, 100)

# Compute the 3 first Rayleigh- and Love- wave modal dispersion curves
# Fundamental mode corresponds to mode 0
pd = PhaseDispersion(*velocity_model.T)
cpr = [pd(t, mode=i, wave="rayleigh") for i in range(3)]
cpl = [pd(t, mode=i, wave="love") for i in range(3)]

Full error message

disba._exception.DispersionError: failed to find root for fundamental mode

System information

• Operating system: win10
• Python installation (Anaconda, system, ETS): Anaconda
• Version of Python: 3.8.5
• Version of this package: 0.4.2

Sensitivity kernel examples in Matplotlib

Hi, thank you for creating this code. I found it very straightforward to install.

I am running into issues with reproducing the example plots that are shown in the example. I can recreate the dispersion curves and normalized eigenfunction plots using Matplotlib within a Jupyter Notebook (see attached pdf containing Jupyter notebook code and outputs). However, when I attempt to recreate the sensitivity kernels and ellipticity outputs, my results do not appear similar to the tutorial (see attached image comparing Rayleigh-wave sensitivity kernels). I'm not sure if this is due to the type of plotting used, or if there is another issue within my implementation of the code. Thank you in advance for your support with this.

disba_example.pdf

Differences between the fast delta matrix algorithm and Dunkin's matrix algorithm

Dear Keurfon Luu,

I test different methods of disba and compare it with the Geopsy using the example model that you give on Github, here are results:


So I am wondering if it is the inherent difference between these two algorithms?

Whether supporting a water layer

Thanks for sharing this powerful tool. I'd like to ask:
Does disba support to calculate dispersion from a model with water layer on the top?

Code for plots in the Readme

Thanks for the super-useful repository!

Small request - the plots in the Readme are very nice, but I couldn't find the code to generate them. Any chance you could add them to the helpers function or somewhere appropriate?

Cheers and thanks again,
Ariel

Dunkin matrix method can find the root while the fast-delta matrix method can't (base order)

Description of the problem

I set a two layer model :

model.true_model

{'thick': [0.002, 0.015],
'vp': [1.2375343056249999, 1.740763080625],
'vs': [0.15, 0.45],
'rho': [1.4501699956971361, 1.7773312121113325]
}

and then I use the dunkin matrix method and fast-delta method to calcualte the dispersion wave,I get a two different result following:

from disba import PhaseDispersion
Velocity_model = np.hstack((thick_true.reshape(-1,1),vp.reshape(-1,1),vs.reshape(-1,1),rho.reshape(-1,1)))
t = np.linspace(1/60,1/5,100)
pd = PhaseDispersion(*Velocity_model.T,algorithm="dunkin")
cpr = [pd(t, mode=i, wave="rayleigh") for i in range(3)]
cpr

from disba import PhaseDispersion
Velocity_model = np.hstack((thick_true.reshape(-1,1),vp.reshape(-1,1),vs.reshape(-1,1),rho.reshape(-1,1)))
t = np.linspace(1/60,1/5,100)
pd = PhaseDispersion(*Velocity_model.T,algorithm="fast-delta")
cpr = [pd(t, mode=i, wave="rayleigh") for i in range(3)]
cpr

System information

• Operating system: Ubuntu
• Python installation (Anaconda, system, ETS):Anaconda python3.8
• Version of Python:python 3.8
• Version of this package:

Size changes when using Ellipticity function with dunkin algorithm

Dear Keurfon Luu,

When computing the ellipticity curve, the size of the ellipticity is different from the size of the period that I give

Full code that generated the difference

import numpy as np
from disba import Ellipticity
model = np.loadtxt('ell_break.txt')
t = np.logspace(-1,1,100)
ell = Ellipticity(*model.T)
rel = ell(t, mode=0)
print('the model is\n',model)
print('the size of the desired period is', t.size)
print('the size of the output period is', rel.period.size)
print('the size of the output ellipticity is', rel.ellipticity.size)

Full difference message

the model is
 [[2.70970250e-02 2.96523805e-01 1.97567919e-01 3.78924966e+00]
 [1.30765033e-01 5.13611569e-01 2.80394454e-01 1.95701986e+00]
 [2.17958244e-01 1.08340722e+00 7.46324600e-01 2.61667395e+00]
 [1.26844333e-05 1.33531494e+00 7.05833449e-01 1.82148673e+00]
 [6.21994491e-02 1.09575716e+00 3.99727585e-01 2.38595491e+00]
 [6.09692959e-01 2.20844656e+00 9.80368015e-01 3.36810416e+00]
 [3.29696606e-01 4.88211654e+00 1.58179215e+00 3.20485749e+00]
 [5.19788596e-01 3.20808230e+00 1.69939325e+00 2.24128211e+00]
 [3.70867802e-02 4.56789817e+00 1.74667706e+00 2.00621080e+00]
 [8.51740987e-01 4.82037862e+00 2.05268480e+00 2.74272310e+00]
 [0.00000000e+00 9.71645057e-01 5.21908871e-01 1.72753223e+00]]
the size of the desired period is 100
the size of the output period is 83
the size of the output ellipticity is 83

For fast-delta algorithm

ell = Ellipticity(*model.T, algorithm='fast-delta')
rel = ell(t, mode=0)
print('using the fast-delta algorithm')
print('the size of the desired period is', t.size)
print('the size of the output period is', rel.period.size)
print('the size of the output ellipticity is', rel.ellipticity.size)

using the fast-delta algorithm
the size of the desired period is 100
the size of the output period is 100
the size of the output ellipticity is 100

I am thinking if the model which I obtained during the inversion process is too complex?

System information

• Operating system: Ubuntu 20.04
• Python installation (Anaconda, system, ETS): Anaconda
• Version of Python: 3.8.5
• Version of this package: 0.5.1

Difference in higher modes when compared with surf96 fortran

Description of the problem

I plot model 0,1,2 from the fortran code and the disba code. While mode 0 is exact the same results, mode 1 and 2 are very different (and seem) out of place.

The plot shows with dots the dispersion curves from the fortran code, the 'x' the results from disba. Mode 0 is right on spot, mode 1 and mode 2 seem error. Any help?

thickness=np.array([0.0005, 0.0006,0.0008,0.0010,0.0013,0.0016,0.0919,0.0])
vs = np.array([0.1250,0.1178,0.1299,0.1451,0.1643,0.1885,0.2,0.5])
vp = vs * 1.73
rho = vp * .32 + .77
    
data=np.c_[thickness,vp,vs,rho]
    # Periods must be sorted starting with low periods
t =1/ np.linspace(1,500, 256)

 pd = PhaseDispersion(*data.T)
 cpr = [pd(t, mode=i, wave="rayleigh") for i in range(3)]
 # cpl = [pd(t, mode=i, wave="love") for i in range(3)]
    
 plt.plot(1/cpr[0][0],1e3*cpr[0][1],'x')
 plt.plot(1/cpr[1][0],1e3*cpr[1][1],'x')
 plt.plot(1/cpr[2][0],1e3*cpr[2][1],'x')

System information

• Operating system: Windows
• Python installation (Anaconda, system, ETS): Anaconda
• Version of Python: 3.8
• Version of this package:
  

Get empty array from disba

Description of the problem

I want simulate some muliti-mode phase-velocity dispersion of near surface layer model.

The target frequency range is [1,100]Hz.Only the fundament dispersion curve can be compated. The first and second modes are empty.

When I change the frequency range to [10,100]Hz，the compuation will not stop.

When I change the frequency range to [20,100]Hz，I can get three modes dispersion curves.

Full code that generated the error

import numpy

from disba import PhaseDispersion

# Velocity model and periods
velocity_model = numpy.array(
    [
        [0.002,0.65,0.194,1.82],
        [0.003,0.75,0.270,1.86],
        [0.004,1.40,0.367,1.91],
        [0.005,1.80,0.485,1.96],
        [0.006,2.15,0.603,2.02],
        [10.00,2.80,0.740,2.09],
    ]
)
freq = numpy.linspace(1.0, 100.0, 50.0)

# Dispersion curve
pd = PhaseDispersion(*velocity_model.T)
labels = {
    0: "Fundamental",
    1: "Mode 1",
    2: "Mode 2",
}
cpss=list()
for wave in ["rayleigh"]:
#    fig = plt.figure()

    for i in range(3):
        cp = pd(1./freq, mode=i, wave=wave)
        cpss.append(cp)

Full error message

PASTE ERROR MESSAGE HERE

System information

• Operating system:Windows 10
• Python installation (Anaconda, system, ETS):Anaconda
• Version of Python:3.7.4
• Version of this package:0.4.0