lsforce

Pipeline status Coverage report Documentation status

lsforce is a Python-based single-force seismic inversion framework for massive landslides. The codes can also be applied to other seismic sources that are well-approximated as a single force (e.g., volcanic eruptions, some glacial events). The library can be used to invert long period (tens to hundreds of seconds) seismic waveforms to estimate a time series vector of single forces that represents the equivalent forces exerted on the Earth by the landslide (see example output figure below).

Example force-time function output by lsforce

Installation

The following has only been tested on macOS.

Clone this repo and run the installation script, which creates a conda environment named lsforce and installs the lsforce package into the environment:

git clone https://code.usgs.gov/ghsc/lhp/lsforce.git
cd lsforce
bash install.sh  # Or `bash install.sh 1` if you want developer tools as well

By default, the Green’s functions used by lsforce come from the Synthetics Engine (Syngine) hosted by IRIS Data Services. The user can choose from a fixed set of 1D Earth models.

Alternatively, if users prefer to compute Green’s functions using a custom model (see Documentation), they can optionally install Computer Programs in Seismology (CPS) via the following:

  1. Install GCC with e.g. Homebrew:

    brew install gcc
    
  2. Complete the CPS license form, download the resulting archive, and unzip

  3. Move the directory PROGRAMS.330 to where you’d like to install, then:

    cd PROGRAMS.330
    ./Setup OSX40
    ./C
    
  4. Add the executables to PATH by adding the following line to e.g. ~/.bash_profile:

    export PATH="$PATH:/path/to/PROGRAMS.330/bin"
    

Documentation

The latest interactive documentation is visible online here.

To instead build the interactive documentation yourself, first ensure that you installed the developer tools (bash install.sh 1), which are required for documentation building. Then:

conda activate lsforce
cd doc
make html
open _build/html/index.html  # macOS command to open file in browser

The lsforce package includes a script, axisem2cps, which can convert 1D Earth models from Syngine into CPS model files. These models can then be further modified for specific use cases. In addition, completely custom CPS model files can be provided; for more information on CPS model files, see Chapter 8 of the CPS documentation. The lsforce conda environment must be active for the script to be available.

Usage examples for the two currently-supported parameterization methods are given in the three Jupyter Notebooks example_full.ipynb, example_triangle.ipynb, and example_lamplugh.ipynb, which are located in the notebooks directory. To open the notebooks, run:

conda activate lsforce
jupyter notebook notebooks

This will start a Jupyter Notebook server and open a new window or tab in your browser with the interactive notebooks displayed.

Testing

Tests are located in the tests directory. To run the tests, first ensure that you installed the developer tools (bash install.sh 1), which are required for testing. Then:

conda activate lsforce
pytest

Citations

Allstadt, K. E., & Toney, L. (2020). lsforce (Version 1.0.1) [Source code]. U.S. Geological Survey Software Release. https://doi.org/10.5066/P9CR20KW

Toney, L., & Allstadt, K. E. (2021). lsforce: A Python-based single-force seismic inversion framework for massive landslides. Seismological Research Letters, 92(4), 2610–2626. https://doi.org/10.1785/0220210004