evodcinv

|License| |Stars| |Pyversions| |Version| |Downloads| |Code style: black| |Codacy Badge| |Codecov| |Build| |Docs| |DOI|

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 <https://github.com/keurfonluu/stochopy>__ for the evolutionary optimizers while forward modeling is heavy-lifted by disba <https://github.com/keurfonluu/disba>__.

.. figure:: https://raw.githubusercontent.com/keurfonluu/evodcinv/master/.github/sample.png :alt: sample :width: 100% :align: center

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:

.. code:: bash

pip install evodcinv --user

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

.. code:: bash

pip install . --user

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

.. code:: bash

pytest

Documentation

Refer to the online documentation <https://keurfonluu.github.io/evodcinv/>__ for detailed description of the API and examples.

Alternatively, the documentation can be built using Sphinx <https://www.sphinx-doc.org/en/master/>__:

.. code:: bash

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).

.. code:: python

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:

.. code-block::

--------------------------------------------------------------------------------
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 <https://github.com/keurfonluu/evodcinv/blob/master/CONTRIBUTING.rst>__ to see how you can help. This project is released with a Code of Conduct <https://github.com/keurfonluu/evodcinv/blob/master/CODE_OF_CONDUCT.rst>__ which you agree to abide by when contributing.

.. |License| image:: https://img.shields.io/github/license/keurfonluu/evodcinv :target: https://github.com/keurfonluu/evodcinv/blob/master/LICENSE

.. |Stars| image:: https://img.shields.io/github/stars/keurfonluu/evodcinv?logo=github :target: https://github.com/keurfonluu/evodcinv

.. |Pyversions| image:: https://img.shields.io/pypi/pyversions/evodcinv.svg?style=flat :target: https://pypi.org/pypi/evodcinv/

.. |Version| image:: https://img.shields.io/pypi/v/evodcinv.svg?style=flat :target: https://pypi.org/project/evodcinv

.. |Downloads| image:: https://pepy.tech/badge/evodcinv :target: https://pepy.tech/project/evodcinv

.. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=flat :target: https://github.com/psf/black

.. |Codacy Badge| image:: https://img.shields.io/codacy/grade/bd53f27ac85d419d996c434353f08760.svg?style=flat :target: https://www.codacy.com/gh/keurfonluu/evodcinv/dashboard?utm_source=github.com&utm_medium=referral&utm_content=keurfonluu/evodcinv&utm_campaign=Badge_Grade

.. |Codecov| image:: https://img.shields.io/codecov/c/github/keurfonluu/evodcinv.svg?style=flat :target: https://codecov.io/gh/keurfonluu/evodcinv

.. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.5775193.svg?style=flat :target: https://doi.org/10.5281/zenodo.5775193

.. |Build| image:: https://img.shields.io/github/actions/workflow/status/keurfonluu/evodcinv/ci.yml :target: https://github.com/keurfonluu/evodcinv

.. |Docs| image:: https://img.shields.io/github/actions/workflow/status/keurfonluu/evodcinv/doc.yml?label=docs :target: https://keurfonluu.github.io/evodcinv/