lsforce

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

Note

This repository exists on two Git platforms:

• USGS GitLab — code.usgs.gov/ghsc/lhp/lsforce (primary)
• GitHub — github.com/DOI-USGS/lsforce (mirror)

The GitHub repository is a read-only mirror of the USGS GitLab repository. It was created to facilitate user interaction and code visibility for the broader community. All issues and pull requests should be submitted to the GitHub repository.

Installation

lsforce has been tested on macOS and Linux.

Clone this repo and run the installation script, which creates an 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

The install script will check if you have the conda or mamba package managers installed. If you have both installed, it will use mamba. If you have neither installed, it will install mamba and then use it. If you only have conda installed, we strongly recommend that you install mamba before running the install script. mamba is much, much faster than conda when solving the lsforce environment.

By default, the Green's functions used by lsforce come from the Synthetics Engine (Syngine) hosted by EarthScope. 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. Run the CPS install script:

   bash install-cps.sh

2. Add the executables to your PATH by adding the following line to e.g. ~/.bash_profile:

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

   The CPS install script will print this location before it exits.

If, after running the steps above, you run into lsforce errors when attempting to use CPS for Green's functions, CPS compilation may have ran into errors. These errors prevent certain programs from being compiled, even though the install script proceeds. Such errors are almost always due to missing compilers. To address this, carefully follow the CPS installation guidance for dependency installation for Linux or macOS.

Documentation

Documentation for lsforce is visible online here.

To build the interactive HTML 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

(To build Markdown documentation, use make markdown.)

The lsforce package includes a command, 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 command 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., & Collins, E. A. (2023). lsforce (Version 1.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

Contacts

Kate Allstadt, kallstadt@usgs.gov
Liam Toney, ltoney@usgs.gov