Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/doi-usgs/lsforce

A Python-based single-force seismic inversion framework for massive landslides
https://github.com/doi-usgs/lsforce

Last synced: about 1 month ago
JSON representation

A Python-based single-force seismic inversion framework for massive landslides

Awesome Lists containing this project

README 

        
*lsforce*

=========



[![Pipeline status](https://code.usgs.gov/ghsc/lhp/lsforce/badges/main/pipeline.svg)](https://code.usgs.gov/ghsc/lhp/lsforce/pipelines/latest) [![Coverage report](https://code.usgs.gov/ghsc/lhp/lsforce/badges/main/coverage.svg)](https://code.usgs.gov/ghsc/lhp/lsforce/-/jobs)



*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](example_force_history.png)



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:

```shell

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`](https://docs.conda.io/en/latest/) or

[`mamba`](https://mamba.readthedocs.io/en/latest/) 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)](https://ds.iris.edu/ds/products/syngine/) hosted by

[IRIS Data Services](https://ds.iris.edu/ds/products/). The user can choose from a fixed

set of [1D Earth models](https://ds.iris.edu/ds/products/syngine/#earth).



Alternatively, if users prefer to compute Green's functions using a custom model (see

[Documentation](#documentation)), they can optionally install

[Computer Programs in Seismology (CPS)](https://rbherrmann.github.io/ComputerProgramsSeismology/)

via the following:



   1. Run the CPS install script:

      ```shell

      bash install-cps.sh

      ```

   2. Add the executables to your `PATH` by adding the following line to e.g.

      `~/.bash_profile`:

      ```shell

      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](https://rbherrmann.github.io/ComputerProgramsSeismology/cpslinux.html)

or

[macOS](https://rbherrmann.github.io/ComputerProgramsSeismology/cpsmacos.html).



Documentation

-------------



Documentation for *lsforce* is visible online

[here](https://ghsc.code-pages.usgs.gov/lhp/lsforce).



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:

```shell

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`](lsforce/axisem2cps.py),

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](https://rbherrmann.github.io/ComputerProgramsSeismology/CPS/CPS330/cps330o.pdf).

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](https://jupyter.org/) `example_full.ipynb`,

`example_triangle.ipynb`, and `example_lamplugh.ipynb`, which are located in the

`notebooks` directory. To open the notebooks, run:

```shell

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.



Mirrors

-------



The primary host for the development of this software is on **code.usgs.gov** (GitLab) here:



- https://code.usgs.gov/ghsc/lhp/lsforce



One drawback of the USGS GitLab is that it's more cumbersome for external users to create an

account and post issues than on GitHub. Hence, we've made a mirror of this repository on GitHub

here:



- https://github.com/DOI-USGS/lsforce



If you have a GitHub account, you can immediately post issues to this mirrored repository.



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:

```shell

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