evodcinv’s documentation#

evodcinv#

evodcinv is a Python library to invert surface wave dispersion data (e.g., phase velocity dispersion curves) for an isotropic layered velocity model using Evolutionary Algorithms. It relies on stochopy for the evolutionary optimizers while forward modeling is heavy-lifted by disba.

sample — Inversion of phase velocity dispersion curve (fundamental mode).#

Features#

Invertible data curves:

Love-wave phase and/or group velocity dispersion curves,
Rayleigh-wave phase and/or group velocity dispersion curves,
Rayleigh-wave ellipticity (experimental).

Installation#

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

pip install evodcinv --user

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

pip install . --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 inverts a Rayleigh-wave phase velocity dispersion curve (fundamental mode).

from evodcinv import EarthModel, Layer, Curve

# Initialize model
model = EarthModel()

# Build model search boundaries from top to bottom
# First argument is the bounds of layer's thickness [km]
# Second argument is the bounds of layer's S-wave velocity [km/s]
model.add(Layer([0.001, 0.1], [0.1, 3.0]))
model.add(Layer([0.001, 0.1], [0.1, 3.0]))

# Configure model
model.configure(
    optimizer="cpso",  # Evolutionary algorithm
    misfit="rmse",  # Misfit function type
    optimizer_args={
        "popsize": 10,  # Population size
        "maxiter": 100,  # Number of iterations
        "workers": -1,  # Number of cores
        "seed": 0,
    },
)

# Define the dispersion curves to invert
# period and velocity are assumed to be data arrays
curves = [Curve(period, velocity, 0, "rayleigh", "phase")]

# Run inversion
res = model.invert(curves)
print(res)

Expected output:

--------------------------------------------------------------------------------
Best model out of 501 models (1 run)

Velocity model                                    Model parameters
----------------------------------------          ------------------------------
         d        vp        vs       rho                   d        vs        nu
      [km]    [km/s]    [km/s]   [g/cm3]                [km]    [km/s]       [-]
----------------------------------------          ------------------------------
    0.0298    0.5033    0.2055    2.0000              0.0298    0.2055    0.4000
    1.0000    2.0586    0.9935    2.0000                   -    0.9935    0.3482
----------------------------------------          ------------------------------

Number of layers: 2
Number of parameters: 5
Best model misfit: 0.0038
--------------------------------------------------------------------------------

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.