Metadata-Version: 2.1
Name: ps2ff
Version: 1.5.8
Summary: Approximated rupture distances from point source
Author-email: Eric Thompson <emthompsone@usgs.gov>, Bruce Worden <cbworden@contractor.usgs.gov>
License: License
        =======
        
        Unless otherwise noted, This project is in the public domain in the United
        States because it contains materials that originally came from the United
        States Geological Survey, an agency of the United States Department of
        Interior. For more information, see the official USGS copyright policy at
        https://www2.usgs.gov/visual-id/credit_usgs.html#copyright
        
        Additionally, we waive copyright and related rights in the work
        worldwide through the CC0 1.0 Universal public domain dedication.
        
        
        CC0 1.0 Universal Summary
        -------------------------
        
        This is a human-readable summary of the
        [Legal Code (read the full text)][1].
        
        
        ### No Copyright
        
        The person who associated a work with this deed has dedicated the work to
        the public domain by waiving all of his or her rights to the work worldwide
        under copyright law, including all related and neighboring rights, to the
        extent allowed by law.
        
        You can copy, modify, distribute and perform the work, even for commercial
        purposes, all without asking permission.
        
        
        ### Other Information
        
        In no way are the patent or trademark rights of any person affected by CC0,
        nor are the rights that other persons may have in the work or in how the
        work is used, such as publicity or privacy rights.
        
        Unless expressly stated otherwise, the person who associated a work with
        this deed makes no warranties about the work, and disclaims liability for
        all uses of the work, to the fullest extent permitted by applicable law.
        When using or citing the work, you should not imply endorsement by the
        author or the affirmer.
        
        
        
        [1]: https://creativecommons.org/publicdomain/zero/1.0/legalcode
        
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: configobj>=5.0.6
Requires-Dist: numpy<2.0,>=1.21
Requires-Dist: pandas>=1.0
Requires-Dist: scipy>=1.7
Provides-Extra: build
Requires-Dist: build; extra == "build"
Requires-Dist: twine; extra == "build"
Provides-Extra: dev
Requires-Dist: build>=0.7.0; extra == "dev"
Requires-Dist: black>=21; extra == "dev"
Requires-Dist: esi-releases>=0.1; extra == "dev"
Requires-Dist: flake8>=3.9; extra == "dev"
Requires-Dist: ipython>=7.26; extra == "dev"
Requires-Dist: pylint>=2.17; extra == "dev"
Provides-Extra: doc
Requires-Dist: altair>=4.2.2; extra == "doc"
Requires-Dist: furo>=2023.3.27; extra == "doc"
Requires-Dist: myst-nb>=0.17.2; extra == "doc"
Requires-Dist: myst-parser>=0.18.1; extra == "doc"
Requires-Dist: nbsphinx>=0.9.1; extra == "doc"
Requires-Dist: recommonmark>=0.7.1; extra == "doc"
Requires-Dist: sphinx>5.0.0; extra == "doc"
Requires-Dist: sphinx-autoapi<3.0.0; extra == "doc"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "doc"
Requires-Dist: sphinx-inline-tabs>=2023.4.21; extra == "doc"
Requires-Dist: sphinxcontrib-programoutput>=0.17; extra == "doc"
Provides-Extra: test
Requires-Dist: pytest>=6.2; extra == "test"
Requires-Dist: pytest-cov>=2.12; extra == "test"
Requires-Dist: pytest-console-scripts>=1.4; extra == "test"
Requires-Dist: vcrpy>=4.1; extra == "test"

ps2ff
=====

<img align="left" height="70" src="https://code.usgs.gov/ghsc/esi/ps2ff/-/raw/main/doc_source/_static/ps2ff_wide.png">
Produce approximated finite fault distances and variance corrections given
point source information, for example Repi (epcentral distance) to Rjb
(Joyner-Boore distance) or Rrup (closest distance to rupture).

<br><br>

Using the results (the API)
---------------------------

The command line programs (described below) can be used to generate new
distance adjustments. This package also includes a set of correction factors
for some common conditions (e.g., typical active crustal regions). These
can most easily be used with the `interpolate` module that contains the `PS2FF`
class, which enables the use of the tables for arbitrary magnitudes and
epicentral distance values. See the `ps2ff.interpolate` section of this
package.

Installation
------------------------------
In the base of this repository, run
```
conda create --name ps2ff pip
conda activate ps2ff
pip install -r requirements.txt .
```
You can omit the conda commands if you do not wish to use a conda virtual environment.

To run the tests
```
pip install pytest
pytest .
```

Background
----------
This code implements the methods descibed by:
- Thompson, E. M., and C. B. Worden (2017). Estimating rupture distances without
  a rupture, *Bulletin of the Seismological Society of America*. 
DOI: https://doi.org/10.1785/0120170174.


Running the Programs
--------------------
The primary program is `run_ps2ff`, which must be given a configuraiton file
```
ps2ff -w Rjb config_file.ini
```
where '-w Rjb' is the 'what' command line argument for `run_ps2ff`.
There are example configuration files in the `ps2ff/config` directory.

Output Tables
-------------
The `ps2ff/tables` directory contains example results for some generic seismological
assumptions. The output file name convension is easiest to describe with an
example:
```
Rjb_S14_mechA_ar1p0_seis0_15_Ratios.csv
```
where:
 - "Rjb" is the the `what` command line argument.
 - "S14" is the selected `rup_dim_model`.
 - "mechA" specifies the rupture mechanism parameter `mech`, where "A" can
   be one of "A", "SS", "N", or "R".
 - "ar1p0" is the aspect ratio specified with the `AR` parameter, where the
   decimal point is replaced with the letter 'p'.
 - "seis0_15" is the range min/max seismogenic depths (in this case 0 to 15
   km).
 - "Ratios" is either "Ratios" or "Var" specifying whether the file contains
   Rjb- or Rrup-to-Repi ratios, or variances.

Each output table starts with six header lines (each beginning with `#`)
specifying the processing parameters. This is followed by a line
(comma-separated) providing the column headers. The first column, "Repi_km",
is the epicentral distance. The following columns "R(magnitude)" ("R" for
"ratio") or "V(magnitude)" ("V" for "variance) provide the values for a given
Repi and magnitude. The table is intended for bi-variate interpolation, linear
in magnitude and logarithmic in distance. The ratios are Rjb (or Rrup) to Repi.


Program Details
---------------

`run_ps2ff` produces tables of Rjb-to-Repi or Rrup-to-Repi ratios and
variances. Example configuration files may be found in ps2ff/config.

`run_ps2ff_single_event` produces tables of Rrup-to-Repi and Rjb-to-Repi
ratios and variances for a single event. This means that the magnitdue and
hypocentral depth are available, simplifying the integration. It optionally
tabulates the adjustment factors as a function of backazimuth. An example
configuration file for this program is given in
`tests/config/test_single.ini`.

