From ea864810b6331f3d656f3f2f73d777eac86609cd Mon Sep 17 00:00:00 2001
From: Peter Powers <pmpowers@usgs.gov>
Date: Sun, 20 Jun 2021 13:11:08 -0600
Subject: [PATCH] docs from wiki
---
docs/About-the-NSHMP.md | 23 +
docs/Building-&-Running.md | 147 +++++
docs/Calculation-Configuration.md | 93 ++++
docs/Developer-Basics.md | 40 ++
docs/Functional-PSHA.md | 109 ++++
docs/Ground-Motion-Models.md | 154 ++++++
docs/Hazard-Model.md | 33 ++
docs/Home.md | 38 ++
docs/Logic-Trees-&-Uncertainty.md | 125 +++++
docs/Magnitude-Frequency-Distributions.md | 239 ++++++++
docs/Model Editions.md | 100 ++++
docs/Model-Files.md | 186 +++++++
docs/Model-Structure.md | 195 +++++++
docs/Rupture-Scaling-Relations.md | 70 +++
docs/Site-Specification.md | 111 ++++
docs/Source-Types.md | 629 ++++++++++++++++++++++
docs/USGS-Models.md | 37 ++
docs/_Sidebar.md | 18 +
docs/images/psha-formula.png | Bin 0 -> 38574 bytes
docs/images/psha-functional.png | Bin 0 -> 11953 bytes
docs/images/psha-linear.png | Bin 0 -> 14814 bytes
docs/images/usgs-icon.png | Bin 0 -> 1098 bytes
22 files changed, 2347 insertions(+)
create mode 100644 docs/About-the-NSHMP.md
create mode 100644 docs/Building-&-Running.md
create mode 100644 docs/Calculation-Configuration.md
create mode 100644 docs/Developer-Basics.md
create mode 100644 docs/Functional-PSHA.md
create mode 100644 docs/Ground-Motion-Models.md
create mode 100644 docs/Hazard-Model.md
create mode 100644 docs/Home.md
create mode 100644 docs/Logic-Trees-&-Uncertainty.md
create mode 100644 docs/Magnitude-Frequency-Distributions.md
create mode 100644 docs/Model Editions.md
create mode 100644 docs/Model-Files.md
create mode 100644 docs/Model-Structure.md
create mode 100644 docs/Rupture-Scaling-Relations.md
create mode 100644 docs/Site-Specification.md
create mode 100644 docs/Source-Types.md
create mode 100644 docs/USGS-Models.md
create mode 100644 docs/_Sidebar.md
create mode 100644 docs/images/psha-formula.png
create mode 100644 docs/images/psha-functional.png
create mode 100644 docs/images/psha-linear.png
create mode 100644 docs/images/usgs-icon.png
diff --git a/docs/About-the-NSHMP.md b/docs/About-the-NSHMP.md
new file mode 100644
index 000000000..0e1c508a2
--- /dev/null
+++ b/docs/About-the-NSHMP.md
@@ -0,0 +1,23 @@
+# About the NSHMP
+
+The National Seismic Hazard Model Project (NSHMP) produces national seismic hazard models (NSHMs)
+for the United States and territories. The project came into existence following passage of the
+Earthquake Hazards Reduction Act of 1977, as amended:
+
+>3A: "Conduct a systematic assessment of the seismic risks in each region of the Nation prone to
+>earthquakes..."
+>
+>J: "Maintain suitable seismic hazard maps in support of building codes for structures and
+>lifelines, including additional maps needed for performance-based design approaches."
+
+The NSHMP primarily produces long-term NSHMs that are used in U.S. building codes and numerous
+other seismic design requirements. The models are used is site-specific analyses and also for
+defining likely earthquake scenarios for emergency planning. NSHMs are considered reference
+(or baseline) models used by the risk, insurance and reinsurance industries, and they are also
+considered in other industries such as real estate lending. A 9-member steering committee of
+academic and industry experts provides technical oversight and recommendations to the NSHMP.
+
+An NSHM defines the set of likely earthquake sources and their rates in a particular region. Given
+parameters of the earhtquake source and a site of interest, ground motion models (GMMs) are used
+to estimate ground shaking from the set of earthquakes. The NSHMP routinely updates NSHMs for the
+U.S. and its territories to consider the best available science.
diff --git a/docs/Building-&-Running.md b/docs/Building-&-Running.md
new file mode 100644
index 000000000..3ef779c83
--- /dev/null
+++ b/docs/Building-&-Running.md
@@ -0,0 +1,147 @@
+# Building & Running
+
+## Related Pages
+
+TODO
+
+## Build & Run Options
+
+* [Build and run locally](#build-and-run-locally)
+* [Run with Docker](#run-with-docker)
+
+## Build and Run Locally
+
+Building and running *nshmp-haz* requires prior installation of Git and Java. Please see the
+[developer basics](developer-basics) page for system configuration guidance.
+
+### Building
+
+Navigate to a location on your system where you want *nshmp-haz* code to reside, clone the
+repository, and compile:
+
+```bash
+cd /path/to/project/directory
+git clone https://code.usgs.gov/ghsc/nshmp/nshmp-haz.git
+cd nshmp-haz
+./gradlew assemble
+```
+
+This creates a single file, `build/libs/nshmp-haz.jar` that may be used for hazard calculations.
+`./gradlew` executes the Gradle Wrapper script (there is a `gradlew.bat` equivalent for Windows
+users using the native command prompt). This executes any tasks (e.g. `assemble`) after
+downloading all required dependencies, including Gradle itself.
+
+### Computing Hazard
+
+The `HazardCalc` program computes hazard curves at one or more sites for a variety of intensity
+measures. For example:
+
+```bash
+java -cp path/to/nshmp-haz.jar gov.usgs.earthquake.nshmp.HazardCalc model sites [config]
+```
+
+At a minimum, the hazard source [model](hazard-model) and the [site](site-specification)(s) at
+which to perform calculations must be specified. The source model should specified a path to a
+directory. A single site may be specified with a string; multiple sites must be specified using
+either a comma-delimited (CSV) or [GeoJSON](http://geojson.org) file. The path to a custom
+[configuration](calculation-configuration) file containing user-specific settings may optionally
+be supplied as a third argument. It can be used to override any calculation settings; if absent
+[default](calculation-configuration) values are used.
+
+See the [examples](/ghsc/nshmp/nshmp-haz-v2/-/tree/master/etc/examples) directory for more details.
+
+### Computing Disaggregations
+
+Like `HazardCalc`, the `DisaggCalc` program performs disaggregations at one or more sites for a
+variety of intensity measures, but requires an additional `returnPeriod` argument, in years. For
+example:
+
+```bash
+java -cp nshmp-haz.jar gov.usgs.earthquake.nshmp.DisaggCalc model sites returnPeriod [config]
+```
+
+Disaggregations build on and output `HazardCalc` results along with other disaggregation specific
+files. Disaggregations also have some independent
+[configuration](calculation-configuration#config-disagg) options.
+
+## Run with [Docker](https://docs.docker.com/install/)
+
+To ensure you are have the latest *nshmp-haz* update, always first pull the image from Docker:
+
+```bash
+docker pull usgs/nshmp-haz
+```
+
+### Docker Memory on Mac
+
+By default, Docker Desktop for Mac is set to use 2 GB runtime memory. To run *nshmp-haz*, the
+memory available to Docker must be [increased](https://docs.docker.com/docker-for-mac/#advanced)
+to a minimum of 4 GB.
+
+### Running
+
+The *nshmp-haz* application may be run as a Docker container which mitigates the need to install
+Git, Java, or other dependencies besides Docker. A public image is available on
+Docker hub at [https://hub.docker.com/r/usgs/nshmp-haz](https://hub.docker.com/r/usgs/nshmp-haz)
+which can be run with:
+
+```bash
+docker run \
+ -e PROGRAM=<disagg | hazard | rate> \
+ -e MODEL=<CONUS-2018 | HAWAII-2021> \
+ -e RETURN_PERIOD=<RETURN_PERIOD> \
+ -v /absolute/path/to/sites/file:/app/sites.<geojson | csv> \
+ -v /absolute/path/to/config/file:/app/config.json \
+ -v /absolute/path/to/output:/app/output \
+ usgs/nshmp-haz
+
+# Example
+docker run \
+ -e PROGRAM=hazard \
+ -e MODEL=CONUS-2018 \
+ -v $(pwd)/sites.geojson:/app/sites.geojson \
+ -v $(pwd)/config.json:/app/config.json \
+ -v $(pwd)/hazout:/app/output \
+ usgs/nshmp-haz
+```
+
+Where: (TODO links below need checking)
+
+* `PROGRAM` is the nshmp-haz program to run:
+ * disagg = `DisaggCalc`
+ * hazard = `HazardCalc`
+ * rate = `RateCalc`
+
+* `MODEL` is the [USGS model (NSHM)](usgs-models) to run:
+ * CONUS-2018: [Conterminous U.S. 2018](https://github.com/usgs/nshm-conus)
+ * HAWAII-2021: [Hawaii 2021](https://code.usgs.gov/ghsc/nshmp/nshm-hawaii)
+
+* `RETURN_PERIOD`, in years, is only required when running a disaggregation
+
+* Other arguments:
+ * (required) The absolute path to a GeoJSON or CSV [site(s)](site-specification) file
+ * CSV example: `$(pwd)/my-csv-sites.csv:/app/sites.csv`
+ * GeoJSON example: `$(pwd)/my-geojson-sites.geojson:/app/sites.geojson`
+ * (optional) The absolute path to a [configuration](calculation-configuration) file
+ * Example: `$(pwd)/my-custom-config.json:/app/config.json`
+ * (required) The absolute path to an output directory
+ * Example: `$(pwd)/my-hazard-output:/app/output`
+
+### Run Customization
+
+When running *nshmp-haz* with Docker the initial (Xms) and maximum (Xmx) JVM memory sizes can
+be set with the environment flag (-e, -env):
+
+```bash
+docker run \
+ -e JAVA_XMS=<JAVA_XMS> \
+ -e JAVA_XMX=<JAVA_XMX> \
+ ...
+ usgs/nshmp-haz
+```
+
+Where:
+
+* `JAVA_XMS` is the intial memory for the JVM (default: system)
+* `JAVA_XMX` is the maximum memory for the JVM (default: 8g)
+
diff --git a/docs/Calculation-Configuration.md b/docs/Calculation-Configuration.md
new file mode 100644
index 000000000..22b7fb0f4
--- /dev/null
+++ b/docs/Calculation-Configuration.md
@@ -0,0 +1,93 @@
+# Calculation Configuration
+
+A `calc-config.json` file _may_ reside at the root of every [hazard model](hazard-model). This
+file, if present, will override any built-in default calculation configuration parameters, as
+listed below. See the [examples](/usgs/nshmp-haz/tree/master/etc/examples) directory, or any
+[USGS model](usgs-models), for concrete examples (TODO decide if last sentence needed and check
+links).
+
+## Calculation Configuration Parameters
+
+Calculation configuration parameters are optional (i.e. defaults are used for missing values) and
+may be overridden. See [building and running](building-&-running) and the
+[examples](/usgs/nshmp-haz/tree/master/etc/examples) for details.
+
+(TODO needs updated javadoc links)
+
+Parameter | Type | Default | Notes |
+--------- | ---- | ------- | ----- |
+__`hazard`__
+ `.exceedanceModel` |`String` | `TRUNCATION_3SIGMA_UPPER` | [`ExceedanceModel`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/ExceedanceModel.html)
+ `.truncationLevel` |`Double` | `3.0` | [1](notes)
+ `.imts` |`String[]` | `[ PGV, PGA, SA0P01, SA0P02, SA0P03, SA0P05, SA0P075, SA0P1, SA0P15, SA0P2, SA0P25, SA0P3, SA0P4, SA0P5, SA0P75, SA1P0, SA1P5, SA2P0, SA3P0, SA4P0, SA5P0, SA7P5, SA10P0 ]` | [`Imt`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/gmm/Imt.html)
+ `.customImls` |`Map<String, Double[]>` | `{}` (empty object) | [2](#notes)
+ `.gmmUncertainty` |`Boolean` | `false` | [3](#notes)
+ `.valueFormat` |`String` | `ANNUAL_RATE` | [`ValueFormat`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/ValueFormat.html)
+__`deagg`__
+ `.bins` |`Object` | | [4](#notes)
+ `.contributorLimit` |`Double` | `0.1` | [5](#notes)
+__`rate`__
+ `.bins` |`Object` | | [6](#notes)
+ `.distance` |`Double` | `20` km
+ `.distributionFormat` |`String` | `INCREMENTAL` | [`DistributionFormat`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/DistributionFormat.html)
+ `.timespan` |`Double` | `30` years
+ `.valueFormat` |`String` | `ANNUAL_RATE` | [`ValueFormat`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/ValueFormat.html)
+__`site`__
+ `.vs30` |`Double` | `760.0` | [`Site`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/Site.html)
+ `.vsInferred` |`Boolean` | `true`
+ `.z1p0` |`Double` | `null` | [7](#notes)
+ `.z2p5` |`Double` | `null` | [7](#notes)
+__`output`__ |
+ `.directory` |`String` | `hazout`
+ `.dataTypes` |`String[]` | `[ TOTAL ]` | [`DataType`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/DataType.html)
+__`performance`__
+ `.optimizeGrids` |`Boolean` | `true` | [8](#notes)
+ `.smoothGrids` |`Boolean` | `true` | [9](#notes)
+ `.systemPartition` |`Integer` | `1000` | [10](#notes)
+ `.threadCount` |`String` | `ALL` | [`ThreadCount`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/ThreadCount.html)
+
+## Notes
+1. `hazard.truncationLevel`: This value is only used if the `hazard.exceedanceModel` requires a
+ limit (e.g. `TRUNCATION_UPPER_ONLY`)
+2. `hazard.gmmUncertainty`: If values for additional epistemic uncertainty on ground motion have
+ been defined, this value en/disables this feature.
+3. `hazard.customImls`: Hazard is computed at default intensity measure levels (IMLs) for every
+ supported intenisty measure type (IMT), but a user can specify different IMLs as needed (see
+ this [example](/usgs/nshmp-haz/blob/master/etc/examples/2-custom-config/config.json) and the
+ table of default IMLs, below).
+4. `disagg.bins`: This field maps to a data container that specifies the following default ranges
+ and intervals for distance, magnitude, and epsilon binning: `"bins": { "rMin": 0.0, "rMax":
+ 1000.0, "Δr": 20.0, "mMin": 4.4, "mMax": 9.4, "Δm": 0.2, "εMin": -3.0, "εMax": 3.0, "Δε": 0.5 }`.
+ The `bins` object must be fully specified; partial overrides do not apply to nested JSON objects.
+5. `disagg.contributorLimit`: Specifies the cutoff (in %) below which contributing sources are not
+ listed in disaggregation results.
+6. `rate.bins`: This field maps to a data container that specifies the following default magnitude
+ binning range and interval: `"bins": { "mMin": 4.2, "mMax": 9.4, "Δm": 0.1 }`. The `bins` object
+ must be fully specified; partial overrides do not apply to nested JSON objects.
+7. `site.z1p0` and `site.z2p5`: Basin terms may be specified as `null` or `NaN` (both unquoted).
+ `null` is preferred as `NaN` does not conform to the JSON spec. When trying to override default
+ values, however, a `null` term will be ignored whereas `NaN` will override any existing value.
+8. `performance.optimizeGrids`: Gridded seismicity source optimizations are currently implemented
+ for any non-fixed strike grid source. For any site, rates across all azimuths are aggregated
+ in tables of distance and magnitude.
+9. `performance.smoothGrids`: Resample gridded seismicity sources close to a site.
+10. `performance.systemPartition`: The number of ruptures in a fault-system source to process
+ concurrently.
+
+## Default Intensity Measure Levels (IMLs)
+
+Units of PGV IMLs are cm/s; all other IMTs are in units of g. Spectral acceleration IMTs that are not listed use the values of the next highest spectral period.
+
+IMT | IMLs
+-----------|-----
+PGV | 0.237, 0.355, 0.532, 0.798, 1.19, 1.80, 2.69, 4.04, 6.06, 9.09, 13.6, 20.5, 30.7, 46.0, 69.0, 103.0, 155.0, 233.0, 349.0, 525.0
+PGA | 0.00233, 0.00350, 0.00524, 0.00786, 0.0118, 0.0177, 0.0265, 0.0398, 0.0597, 0.0896, 0.134, 0.202, 0.302, 0.454, 0.680, 1.02, 1.53, 2.30, 3.44, 5.17
+T ≤ 0.01 s | 0.00233, 0.00350, 0.00524, 0.00786, 0.0118, 0.0177, 0.0265, 0.0398, 0.0597, 0.0896, 0.134, 0.202, 0.302, 0.454, 0.680, 1.02, 1.53, 2.30, 3.44, 5.17
+T ≤ 0.02 s | 0.00283, 0.00424, 0.00637, 0.00955, 0.0143, 0.0215, 0.0322, 0.0483, 0.0725, 0.109, 0.163, 0.245, 0.367, 0.551, 0.826, 1.24, 1.86, 2.79, 4.18, 6.27
+T ≤ 0.05 s | 0.00333, 0.00499, 0.00749, 0.0112, 0.0169, 0.0253, 0.0379, 0.0569, 0.0853, 0.128, 0.192, 0.288, 0.432, 0.648, 0.972, 1.46, 2.19, 3.28, 4.92, 7.38
+T ≤ 2 s | 0.00250, 0.00375, 0.00562, 0.00843, 0.0126, 0.0190, 0.0284, 0.0427, 0.0640, 0.0960, 0.144, 0.216, 0.324, 0.486, 0.729, 1.09, 1.64, 2.46, 3.69, 5.54
+T ≤ 3 s | 0.00200, 0.00300, 0.00449, 0.00674, 0.0101, 0.0152, 0.0228, 0.0341, 0.0512, 0.0768, 0.115, 0.173, 0.259, 0.389, 0.583, 0.875, 1.31, 1.97, 2.95, 4.43
+T ≤ 4 s | 0.00133, 0.00200, 0.00300, 0.00449, 0.00674, 0.0101, 0.0152, 0.0228, 0.0341, 0.0512, 0.0768, 0.115, 0.173, 0.259, 0.389, 0.583, 0.875, 1.31, 1.97, 2.95
+T ≤ 5 s | 0.000999, 0.00150, 0.00225, 0.00337, 0.00506, 0.00758, 0.0114, 0.0171, 0.0256, 0.0384, 0.0576, 0.0864, 0.130, 0.194, 0.292, 0.437, 0.656, 0.984, 1.48, 2.21
+T ≤ 7.5 s | 0.000499, 0.000749, 0.00112, 0.00169, 0.00253, 0.00379, 0.00569, 0.00853, 0.0128, 0.0192, 0.0288, 0.0432, 0.0648, 0.0972, 0.146, 0.219, 0.328, 0.492, 0.738, 1.11
+T ≤ 10 s | 0.000333, 0.000499, 0.000749, 0.00112, 0.00169, 0.00253, 0.00379, 0.00569, 0.00853, 0.0128, 0.0192, 0.0288, 0.0432, 0.0648, 0.0972, 0.146, 0.219, 0.328, 0.492, 0.738
diff --git a/docs/Developer-Basics.md b/docs/Developer-Basics.md
new file mode 100644
index 000000000..0010c11fe
--- /dev/null
+++ b/docs/Developer-Basics.md
@@ -0,0 +1,40 @@
+# Developer Basics
+
+The following provides basic guidance on how to set up command-line use of nshmp-haz.
+
+## Required Software
+
+* Java 11 JDK: [Oracle](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html) or [Amazon Corretto](https://docs.aws.amazon.com/corretto/latest/corretto-11-ug/downloads-list.html)
+* [Git](https://git-scm.com/downloads)
+ * Git is a distributed version control system. The USGS uses a [GitLab](https://docs.gitlab.com) [instance](https://code.usgs.gov/) to host projects and facilitate sharing and collaborative development of code. Git is included in the macOS [developer tools](https://developer.apple.com/xcode/).
+ * Windows users may want to consider [Git for Windows](https://git-for-windows.github.io) or [GitHub Desktop](https://desktop.github.com), both of which include a linux-like terminal (Git BASH) in which subsequent commands listed here will work.
+
+Other project dependencies are managed with [Gradle](https://gradle.org/), which does not require a separate installation. Gradle is clever about finding Java, but some users may have to explicitly define a `JAVA_HOME` environment variable. For example, on Unix-like systems with `bash` as the default shell, one might add the following to `~/.bash_profile`:
+
+```bash
+# macOS
+export JAVA_HOME="$(/usr/libexec/java_home -v 11)"
+# Linux
+export JAVA_HOME=/usr/lib/jvm/jdk-11.0.6.jdk
+```
+
+On Windows systems, environment variables are set through the `System Properties > Advanced > Environment Variables...` control panel. Depending on where Java is installed, `JAVA_HOME` might be:
+
+```bash
+JAVA_HOME C:\Program Files\Java\jdk-11.0.6.jdk
+```
+
+## Set Up Git
+
+Follow the [GitLab instructions](https://docs.gitlab.com/ee/topics/git/). Some users may find it easier to use [Git for Windows](https://git-for-windows.github.io) or [GitHub Desktop](https://desktop.github.com). These desktop applications install required system components and are helpful for managing communication between local and remote repositories and viewing file diffs as one makes changes.
+
+## Get the Code
+
+```bash
+cd /directory/for/code
+git clone https://code.usgs.gov/ghsc/nshmp/nshmp-haz.git
+```
+
+## Eclipse Integration (Optional)
+
+Eclipse provides automatic compilation, syntax highlighting, and integration with Git, among other useful features. To build or modify *nshmp-haz* using [Eclipse](http://www.eclipse.org/), install the [Eclipse IDE for Java Developers](https://www.eclipse.org/downloads/packages/) or [Eclipse IDE for Enterprise Java and Web Developers](https://www.eclipse.org/downloads/packages/), if you plan on developing web services. Import the project into Eclipse: `File > Import > Gradle > Existing Gradle Project`
diff --git a/docs/Functional-PSHA.md b/docs/Functional-PSHA.md
new file mode 100644
index 000000000..b97aa9a37
--- /dev/null
+++ b/docs/Functional-PSHA.md
@@ -0,0 +1,109 @@
+### Abstract
+
+Probabilistic seismic hazard analysis (PSHA; Cornell, 1968) is elegant in its relative simplicity. However, in the more than 40-years since its publication, the methodology has come to be applied to increasingly complex and non-standard source and ground motion models. For example, the third Uniform California Earthquake Rupture Forecast ([UCERF3](http://pubs.usgs.gov/of/2013/1165/)) upended the notion of discrete faults as independent sources, and the USGS national seismic hazard model uses temporally clustered sources. Moreover, as the logic trees typically employed in PSHAs to capture epistemic uncertainty grow larger, so too does the demand for a more complete understanding of uncertainty. At the USGS, there are additional requirements to support source model mining, deaggregation, and map-making, often through the use of dynamic web-applications. Implementations of the PSHA methodology commonly iterate over all sources that influence the hazard at a site and sequentially build a single hazard curve. Such a linear PSHA computational pipeline, however, proves difficult to maintain and modify to support the additional complexity of new models, hazard products, and analyses. The functional programming paradigm offers some relief. The functional approach breaks calculations down into their component parts or steps, storing intermediate results as immutable objects, making it easier to: chain actions together; preserve intermediate data or results that may still be relevant (e.g. as in a deaggregation); and leverage the concurrency supported by many modern programming languages.
+
+#### Traditional PSHA formulation (after Baker, 2013):
+
+
+Briefly, the rate, *λ*, of exceeding an intensity measure, *IM*, level may be computed as a summation of the rate of exceeding such a level for all relevant earthquake sources (discretized in magnitude, *M*, and distance, *R*). This formulation relies on models of ground motion that give the probability that an intensity measure level of interest will be exceeded conditioned on the occurrence of a particular earthquake. Such models are commonly referred to as:
+
+* __Intensity measure relationships__
+* __Attenuation relationships__
+* __Ground motion prediction equations (GMPEs)__
+* __Ground motion models (GMMs)__
+
+The parameterization of modern models (e.g. NGA-West2; Bozorgnia et al., 2014) extends to much more than magnitude and distance, including, but not limited to:
+
+* __Multiple distance metrics__ (e.g. rJB, rRup, rX, rY)
+* __Fault geometry__ (e.g. dip, width, rupture depth, hypocentral depth)
+* __Site characteristics__ (e.g. basin depth terms, site type or Vs30 value)
+
+#### Simple, yes, but used for so much more…
+
+While this formulation is relatively straightforward and is typically presented with examples for a single site, using a single GMM, and a nominal number of sources, modern PSHAs commonly include:
+
+* Multiple thousands of sources (e.g. the 2014 USGS NSHM in the Central & Eastern US includes all smoothed seismicity sources out to 1000km from a site).
+* Different source types, the relative contributions of which are important, and the GMM parameterizations of which may be different.
+* Sources (and associated ruptures – source filling or floating) represented by logic trees of magnitude-frequency distributions (MFDs).
+* Source MFDs subject to logic trees of uncertainty on Mmax, total rate (for the individual source, or over a region, e.g. as in UCERF3) or other properties of the distribution.
+* Logic trees of magnitude scaling relations for each source.
+* Source models that do not adhere to the traditional formulation (e.g. cluster models of the NSHM).
+* Logic trees of ground motion models.
+
+#### And further extended to support…
+
+* Response Spectra, Conditional Mean Spectra – multiple intensity measure types (IMTs; e.g. PGA, PGD, PGV, multiple SAs)
+* Deaggregation
+* Banded deaggregation (multiple deaggregations at varying IMLs)
+* Maps – many thousands of sites
+* Uncertainty analyses
+
+#### How are such calculations managed?
+
+* PSHA codes typically compute hazard in a linear fashion, looping over all relevant sources for a site.
+* Adding additional GMMs, logic trees, IMT’s, and sites is addressed with more, outer loops:
+```PHP
+foreach IMT {
+ foreach Site {
+ foreach SourceType {
+ foreach GMM {
+ foreach Source {
+ // do something
+ }
+ }
+ }
+ }
+}
+```
+* Support for secondary analyses, such as deaggregation is supplied by a separate code or codes and can require repeating many of the steps performed to generate an initial hazard curve.
+
+#### What about scaleability, maintenance, and performance?
+
+* Although scaleability can be addressed for secondary products, such as maps, by distributing individual site calculations over multiple processors and threads, it is often difficult to leverage multi-core systems for individual site calculations. This hampers one’s ability to leverage multi-core systems in the face of ever more complex source and ground motion models and their respective logic trees.
+* A linear pipeline complicates testing, requiring end to end tests rather than tests of discrete calculations.
+* Multiple codes repeating identical tasks invite error and complicate maintenance by multiple individuals.
+
+#### Enter functional programming…
+
+* http://en.wikipedia.org/wiki/Functional_programming
+* Functional programming languages have been around for some time (e.g. Haskell, Lisp, R), and fundamental aspects of functional programming/design are common in many languages. For example, a cornerstone of the functional paradigm is the anonymous (or lambda) function; in Matlab, one may write [sqr = @(x) x.^2;].
+* In Matlab, one may pass function ‘handles’ (references) to other functions as arguments. This is also possible in Javascript, where such handles serve as callbacks. Given the rise in popularity of the functional style, Java 8 recently added constructs in the form of the function and streaming APIs, and libraries exists for other languages.
+
+#### How do PSHA and related calculations leverage such an approach?
+
+Break the traditional PSHA formulation down into discrete steps and preserve the data associated with each step:
+
+* **[1]** Source & Site parameterization
+* **[2]** Ground motion calculation (mean and standard deviation only)
+* **[3]** Exceedance curve calculation (per source)
+* **[4]** Recombine
+
+Whereas the traditional pipeline looks something like this:
+
+
+
+The functional pipeline can be processed stepwise:
+
+
+
+**Need a deagreggation?** Revisit and parse the results of steps 1 and 2
+
+**Need a response spectra?** Spawn more calculations, one for each IMT, at step 2.
+
+#### Benefits:
+
+* It’s possible to build a single calculation pipeline that will handle a standard hazard curve calculation and all of its extensions without repetition.
+* Pipeline performance scales with available hardware.
+* No redundant code.
+* Can add or remove transforms or data at any point in the pipeline, or build new pipelines without adversely affecting existing code.
+
+#### Drawbacks:
+
+* Greater memory requirements.
+* Additional (processor) work to manage the flow of calculation steps.
+
+#### References
+
+* Baker J.W. (2013). An Introduction to Probabilistic Seismic Hazard Analysis (PSHA), White Paper, Version 2.0, 79 pp.
+* Bozorgnia, Y., et al. (2014) NGA-West2 Research Project, *Earthquake Spectra*, Vol. 30, No. 3, pp. 973-987.
+* Cornell, C.A., 1968, Engineering seismic risk analysis, *Bulletin of the Seismological Society of America*, Vol. 58, No. 5, pp. 1583-1606.
diff --git a/docs/Ground-Motion-Models.md b/docs/Ground-Motion-Models.md
new file mode 100644
index 000000000..91aec294a
--- /dev/null
+++ b/docs/Ground-Motion-Models.md
@@ -0,0 +1,154 @@
+# Ground Motion Models (GMMs)
+
+Ground motion models (GMMs) forecast the range of ground motions that may occur conditioned on
+the occurrence of various earthquakes. The following tables list the GMMs supported in NSHMs. It
+is not uncommon for a GMM to have multiple concrete implementations. For instance, most subduction
+GMMs, as published, support both interface and intraslab events.
+
+[[_TOC_]]
+
+* How to add links to javadocs? ...not possible in wiki (separate repo)? except with external
+ http gitlab urls?
+* include NSHM that used each model?
+* save horizontal space in table by moving notes to table footnotes. this has to be done manually
+ (see NGA-East model IDs), since markdown footnotes always appear at the bottom of the page
+
+**gmm-config.json** Required adjacent to any `gmm-tree.json`. This file specifies the applicability
+distance of the associated GMM's and any additional epistemic uncertainty model and properties to
+apply to median ground motions derived from the GMM's. This uncertainty is distinct from the
+built-in aleatory variability (standard deviation or sigma) of the GMM's themselves. Use `null`
+values to indicate that no additional uncertainty model should be applied. Supported uncertainty
+models are detailed in the [ground motion models](ground-motion-models) section. For example:
+
+```json
+{
+ "max-distance": 300.0,
+ "epistemic-model": null,
+ "epistemic-tree": null
+}
+```
+
+## GMM Configuration
+
+A `gmm-config.json` file governs how GMMs are applied in a NSHM. It specifies a maximum distance
+at which a GMM is applicable. It may also specify a model of additional epistemic uncertainty and
+the logic tree used to apply it. If no such model is required, the `epistemic-model` and
+`epistemic-tree` members must be `null`. See [Uncertainties in NSHMs](uncertainties-in-nshms) for
+details on additional epistemic uncertainty in GMMs.
+
+```json
+{
+ "max-distance": 300.0,
+ "epistemic-model": "NGA_WEST2",
+ "epistemic-tree": [
+ { "id": "epi+", "weight": 0.185, "value": 1.0 },
+ { "id": "none", "weight": 0.63, "value": 0.0 },
+ { "id": "epi-", "weight": 0.185, "value": -1.0 }
+ ]
+}
+```
+
+## GMM Uncertainty Models
+
+TODO
+
+## GMM Post Processors
+
+TODO
+
+## Active Crust GMMs
+
+| Reference | ID | Component | Notes |
+|:---------:|:--:|:---------:|:------|
+| **NGA-West 2** | | |
+| [Abrahamson et al., 2014](http://dx.doi.org/10.1193/070913EQS198M) | ASK_14<br>ASK_14_BASIN | RotD50 | |
+| [Boore et al., 2014](http://dx.doi.org/10.1193/070113EQS184M) | BSSA_14<br>BSSA_14_BASIN | RotD50 | |
+| [Campbell & Bozorgnia, 2014](http://dx.doi.org/10.1193/062913EQS175M)| CB_14<br>CB_14_BASIN | RotD50 | |
+| [Chiou & Youngs, 2014](http://dx.doi.org/10.1193/072813EQS219M) | CY_14<br>CY_14_BASIN | RotD50 | |
+| [Idriss, 2014](http://dx.doi.org/10.1193/070613EQS195M) | IDRISS_14 | RotD50 | |
+| **NGA-West 1** | | | |
+| [Boore & Anderson, 2008](http://dx.doi.org/10.1193/1.2830434) | BA_08 | GMRotI50 | |
+| [Campbell & Bozorgnia, 2008](http://dx.doi.org/10.1193/1.2857546) | CB_08 | GMRotI50 | |
+| [Chiou & Youngs, 2008](http://dx.doi.org/10.1193/1.2894832) | CY_08 | GMRotI50 | |
+| **Other** | | | |
+| [Abrahamson & Silva, 1997](http://dx.doi.org/10.1785/gssrl.68.1.94) | AS_97 | Average horizontal | |
+| [Boore et al., 1997](http://dx.doi.org/10.1785/gssrl.68.1.128)<br>[Boore, 2005](http://dx.doi.org/10.1785/gssrl.76.3.368) | BJF_97 | Random horizontal | Soft rock sites only (Vs30 760 m/s) |
+| [Campbell, 1997](http://dx.doi.org/10.1785/gssrl.68.1.154)<br>[errata, 2000](http://dx.doi.org/10.1785/gssrl.71.3.352)<br>[errata, 2001](http://dx.doi.org/10.1785/gssrl.72.4.474) | CAMPBELL_97 | Geometric mean of two horizontal components | Soft rock sites only (Vs30 760 m/s) |
+| [Campbell & Bozorgnia, 2003](http://dx.doi.org/10.1785/0120020029)<br>[errata, 2003](http://dx.doi.org/10.1785/0120030099)<br>[errata, 2003](http://dx.doi.org/10.1785/0120030143) | CB_03 | Average horizontal | Soft rock sites only (Vs30 760 m/s) |
+| [McVerry et al., 2000](http://doi.org/10.5459/BNZSEE.39.1.1-58) | MCVERRY_00_CRUSTAL<br>MCVERRY_00_VOLCANIC | Max-horizontal implemented, model also supports geometric mean | New Zealand, does not correspond directly with US site class model |
+| [Sadigh et al., 1997](http://dx.doi.org/10.1785/gssrl.68.1.180) | SADIGH_97 | Geometric mean of two horizontal components | Also used for interface sources in 2007 Alaska NSHM |
+| [Zhao et al., 2016](http://dx.doi.org/10.1785/0120150063) | ZHAO_16_SHALLOW_CRUST<br>ZHAO_16_UPPER_MANTLE | Geometric mean of two randomly oriented horizontal components | |
+
+## Stable Crust GMMs
+
+| Reference | ID | Component | Notes |
+|:---------:|:--:|:---------:|:------|
+| [Atkinson, 2008](http://dx.doi.org/10.1785/0120070199)<br>[Atkinson & Boore, 2011](http://dx.doi.org/10.1785/0120100270) | ATKINSON_08_PRIME | horizontal | Mean values clamped |
+| [Atkinson & Boore, 2006](http://dx.doi.org/10.1785/0120050245) | AB_06_140BAR<br>AB_06_200BAR<br>AB_06_140BAR_AB<br>AB_06_200BAR_AB<br>AB_06_140BAR_J<br>AB_06_200BAR_J | horizontal | Mean values clamped |
+| [Atkinson & Boore, 2006](http://dx.doi.org/10.1785/0120050245)<br>[Atkinson & Boore, 2011](http://dx.doi.org/10.1785/0120100270) | AB_06_PRIME | horizontal | Mean values clamped |
+| [Campbell, 2003](http://dx.doi.org/10.1785/0120020002) | CAMPBELL_03<br>CAMPBELL_03_AB<br>CAMPBELL_03_J | Geometric mean of two horizontal components | Mean values clamped |
+| [Frankel et al., 1996](https://pubs.usgs.gov/of/1996/532/) | FRANKEL_96<br>FRANKEL_96_AB<br>FRANKEL_96_J | not specified | Mean values clamped |
+| [Graizer & Kalkan, 2015](http://dx.doi.org/10.3133/ofr20151009)<br>[Graizer & Kalkan, 2016](http://dx.doi.org/10.1785/0120150194) | GK_15 | Geometric mean of two randomly oriented horizontal components | |
+| NGA-East<br>[Goulet et al., 2017](https://peer.berkeley.edu/sites/default/files/christine-a-goulet-yousef-bozorgnia-2017_03_0.pdf) | NGA_EAST_USGS [:one:](#one-nga-east-median-model-ids)<br>NGA_EAST_USGS_SEEDS[:two:](#two-nga-east-seed-model-ids) | RotD50 (average horizontal) | Mean values are not clamped |
+| [Pezeshk et al., 2011](http://dx.doi.org/10.1785/0120100144) | PEZESHK_11 | GMRotI50 | Mean values clamped |
+| [Shahjouei and Pezeshk, 2016](http://dx.doi.org/10.1785/0120140367) | NGA_EAST_SEED_SP16 | RotD50 | NGA-East Seed |
+| [Silva et al., 2002](http://www.pacificengineering.org/CEUS/Development%20of%20Regional%20Hard_ABC.pdf) | SILVA_02<br>SILVA_02_AB<br>SILVA_02_J | average horizontal component | Mean values clamped |
+| [Somerville et al., 2001](https://earthquake.usgs.gov/static/lfs/nshm/conterminous/2008/99HQGR0098.pdf) | SOMERVILLE_01 | not specified | Mean values clamped |
+| [Tavakoli & Pezeshk, 2005](http://dx.doi.org/10.1785/0120050030) | TP_05<br>TP_05_AB<br>TP_05_J | not specified | Mean values clamped |
+| [Toro et al., 1997](http://dx.doi.org/10.1785/gssrl.68.1.41)<br>[Toro, 2002](http://www.ce.memphis.edu/7137/PDFs/attenuations/Toro_2001_(modification_1997).pdf) | TORO_97_MB<br>TORO_97_MW | not specified | Mean values clamped |
+
+<a id="one-nga-east-median-model-ids"></a>
+:one: NGA-East Median Model IDs: NGA_EAST_USGS_1, NGA_EAST_USGS_2, NGA_EAST_USGS_3, NGA_EAST_USGS_4, NGA_EAST_USGS_5, NGA_EAST_USGS_6, NGA_EAST_USGS_7, NGA_EAST_USGS_8, NGA_EAST_USGS_9, NGA_EAST_USGS_10, NGA_EAST_USGS_11, NGA_EAST_USGS_12, NGA_EAST_USGS_13, NGA_EAST_USGS_14, NGA_EAST_USGS_15, NGA_EAST_USGS_16, NGA_EAST_USGS_17
+
+<a id="one-nga-east-seed-model-ids"></a>
+:two: NGA-East Seed Model IDs: NGA_EAST_SEED_1CCSP, NGA_EAST_SEED_1CVSP, NGA_EAST_SEED_2CCSP, NGA_EAST_SEED_2CVSP, NGA_EAST_SEED_B_A04, NGA_EAST_SEED_B_AB14, NGA_EAST_SEED_B_AB95, NGA_EAST_SEED_B_BCA10D, NGA_EAST_SEED_B_BS11, NGA_EAST_SEED_B_SGD02, NGA_EAST_SEED_FRANKEL, NGA_EAST_SEED_GRAIZER, NGA_EAST_SEED_GRAIZER16, NGA_EAST_SEED_GRAIZER17, NGA_EAST_SEED_HA15, NGA_EAST_SEED_PEER_EX, NGA_EAST_SEED_PEER_GP, NGA_EAST_SEED_PZCT15_M1SS, NGA_EAST_SEED_PZCT15_M2ES, NGA_EAST_SEED_SP15, NGA_EAST_SEED_SP16, NGA_EAST_SEED_YA15
+
+## Subduction GMMs
+
+| Reference | ID | Component | Notes |
+|:---------:|:--:|:---------:|:------|
+| [Atkinson & Boore, 2003](http://dx.doi.org/10.1785/0120020156) | AB_03_GLOBAL_INTERFACE<br>AB_03_GLOBAL_SLAB<br>AB_03_GLOBAL_SLAB_LOW_SAT<br>AB_03_CASCADIA_INTERFACE<br>AB_03_CASCADIA_SLAB<br>AB_03_CASCADIA_SLAB_LOW_SAT | horizontal | |
+| [Atkinson & Macias, 2009](http://dx.doi.org/10.1785/0120080147) | AM_09_INTERFACE<br>AM_09_INTERFACE_BASIN | Geometric mean of two horizontal components | Interface only |
+| BC Hydro<br>[Abrahamson et al., 2016](http://dx.doi.org/10.1193/051712EQS188MR) | BCHYDRO_12_INTERFACE<br>BCHYDRO_12_INTERFACE_BACKARC<br>BCHYDRO_12_INTERFACE_BASIN<br>BCHYDRO_12_INTERFACE_BASIN_BACKARC<br>BCHYDRO_12_SLAB<br>BCHYDRO_12_SLAB_BACKARC<br>BCHYDRO_12_SLAB_BASIN<br>BCHYDRO_12_SLAB_BASIN_BACKARC | Geometric mean of two horizontal components | |
+| [McVerry et al., 2000](http://doi.org/10.5459/BNZSEE.39.1.1-58) | MCVERRY_00_INTERFACE<br>MCVERRY_00_SLAB<br>MCVERRY_00_VOLCANIC | Max-horizontal implemented, model also supports geometric mean | New Zealand, does not correspond directly with US site class model |
+| NGA-Subduction<br>[Abrahamson et al., 2018](https://peer.berkeley.edu/sites/default/files/2018_02_abrahamson_9.10.18.pdf) | NGA_SUB_USGS_INTERFACE<br>NGA_SUB_USGS_INTERFACE_NO_EPI<br>NGA_SUB_USGS_SLAB<br>NGA_SUB_USGS_SLAB_NO_EPI | Geometric mean of two horizontal components | **Likely to be superseded by final EQS paper**<br>Calibrated for Cascadia use only |
+| [Youngs et al., 1997](http://dx.doi.org/10.1785/gssrl.68.1.58) | YOUNGS_97_INTERFACE<br>YOUNGS_97_SLAB | Geometric mean of two horizontal components | |
+| [Zhao et al., 2006](http://dx.doi.org/10.1785/0120050122) | ZHAO_06_INTERFACE<br>ZHAO_06_INTERFACE_BASIN<br>ZHAO_06_SLAB<br>ZHAO_06_SLAB_BASIN | Geometric mean of two horizontal components | |
+| [Zhao et al., 2016](http://dx.doi.org/10.1785/0120150034)<br>[Zhao et al., 2016](http://dx.doi.org/10.1785/0120150056) | ZHAO_16_INTERFACE<br>ZHAO_16_SLAB<br>*ZHAO_16_UPPER_MANTLE* | Geometric mean of two randomly oriented horizontal components | Subduction Slab and Interface |
+
+## Regional and Specialized GMMs
+
+| Reference | ID | Component | Notes |
+|:---------:|:--:|:---------:|:------|
+| **Hawaii** | | | |
+| [Atkinson, 2010](http://dx.doi.org/10.1785/0120090098) | ATKINSON_10 | geometric mean of two horizontal components | |
+| [Munson & Thurber, 1997](https://pubs.geoscienceworld.org/ssa/srl/article-abstract/68/1/41/142160/Model-of-Strong-Ground-Motions-from-Earthquakes-in) | MT_97 | Larger of two horizontal | PGA and 0.2 seconds, additional term applied for M > 7 |
+| [Wong et al., 2015](http://doi.org/10.1193/012012EQS015M) | WONG_15 | average horizontal | |
+| **New Zealand** | | | |
+| [McVerry et al., 2000](http://doi.org/10.5459/BNZSEE.39.1.1-58) | MCVERRY_00_CRUSTAL<br>MCVERRY_00_VOLCANIC<br>MCVERRY_00_INTERFACE<br>MCVERRY_00_SLAB | Max-horizontal implemented, model also supports geometric mean | New Zealand, does not correspond directly with US site class model. |
+| **Induced Seismicity** | | | |
+| [Atkinson, 2015](http://dx.doi.org/10.1785/0120140142) | ATKINSON_15 | orientation-independent horizontal | |
+<!--
+## Hawaii GMMs
+
+| Reference | ID | Component | Notes |
+|:---------:|:--:|:---------:|:------|
+| [Atkinson, 2010](http://dx.doi.org/10.1785/0120090098) | ATKINSON_10 | geometric mean of two horizontal components | Hawaii |
+| [Munson & Thurber, 1997](https://pubs.geoscienceworld.org/ssa/srl/article-abstract/68/1/41/142160/Model-of-Strong-Ground-Motions-from-Earthquakes-in) | MT_97 | Larger of two horizontal | PGA and 0.2 seconds, additional term applied for M > 7 |
+| [Wong et al., 2015](http://doi.org/10.1193/012012EQS015M) | WONG_15 | average horizontal | |
+
+## Induced Seismicity GMMs
+
+| Reference | ID | Component | Notes |
+|:---------:|:--:|:---------:|:------|
+| [Atkinson, 2015](http://dx.doi.org/10.1785/0120140142) | ATKINSON_15 | orientation-independent horizontal | |
+-->
+
+## Auxilliary Models
+
+Auxilliary models are not used directly, they can be used by concrete implementations of GMMs to modify model output.
+
+| Reference | Purpose | Component | Notes |
+|:---------:|:-------:|:---------:|:------|
+| [Rezaeian et al., 2014](http://dx.doi.org/10.1193/100512EQS298M) | Damping scaling factor | Average horizontal component | No effect if supplied damping ratio is 5% |
+| USGS PGV | Conditional PGV for crustal earthquakes | Horizontal component | Conditional model for vertical component not yet implemented |
diff --git a/docs/Hazard-Model.md b/docs/Hazard-Model.md
new file mode 100644
index 000000000..005e738f1
--- /dev/null
+++ b/docs/Hazard-Model.md
@@ -0,0 +1,33 @@
+# Hazard Model
+
+A USGS seismic hazard model defines earthquake sources, the different rupture scenarios for each,
+and the ground motion models to use with each scenario. Earthquake sources are representations of
+geologic structures on which earthquake ruptures occur with some rate. They can be well defined
+faults with a specific geometry, or uniformely distributed point source representations with rates
+derived from historic earthquake catalogs. In either case, there may be multiple source geometries,
+or earthquake sizes and rates, associated with a given source.
+
+Epistemic uncertainty in source and ground motion models is represented with logic trees. The model
+file formats and structure adopted here leverage the heirarchical organization of file systems to
+support modeling of complex logic trees.
+
+## Related Pages
+
+* [Model Structure](model-structure)
+* [Model Files](model-files)
+* [Source Types](source-types)
+* [Magnitude-Frequency Distributions (MFDs)](magnitude-frequency-distributions-mfds)
+* [Rupture-Scaling Relations](magnitude-scaling-relations)
+* [Ground Motion Models (GMMs)](ground-motion-models-gmms)
+
+## Model Applicability
+
+* NOTE FOR HAZARD CURVE DATA: While the gridded hazard curve data includes ground motions at long
+ return periods, the USGS does not recommend using hazard values below 10<sup>-5</sup> (100,000
+ years), and cautions users using values below 10<sup>-4</sup> (10,000 years). These models were
+ developed for building codes concerned with return periods of 10<sup>-4</sup> and above.
+
+* Important considerations when using NSHMs: NSHMs are only applicable to U.S. and it's
+ territories. Although hazard close to the borders can be useful for comparison to other models,
+ the further one drifts from the U.S. border, the more incomplete the underlying earthquake
+ source model will be.
diff --git a/docs/Home.md b/docs/Home.md
new file mode 100644
index 000000000..7cd65d878
--- /dev/null
+++ b/docs/Home.md
@@ -0,0 +1,38 @@
+# Documentation: nshmp-haz
+
+***nshmp-haz*** is a USGS developed software stack that supports probabilistic seismic hazard
+(PSHA) and related analyses. It is maintained by the National Seismic Hazard Model Project
+([NSHMP](https://earthquake.usgs.gov/hazards/)) within the U.S. Geological Survey's
+([USGS](https://www.usgs.gov)) earthquake hazards program ([EHP](http://earthquake.usgs.gov)).
+
+*nshmp-haz* supports high performance seismic hazard calculations required to generate detailed
+maps over large areas and supports a variety of USGS web services and applications related to
+seismic hazards research and the dissemination of hazard data. This documentation explains how
+to use *nshmp-haz* as well as underlying model implementation details.
+
+## Table of Contents
+
+* [About the NSHMP](about-the-nshmp)
+* [Building & Running](building-&-running)
+ * [Developer Basics](developer-basics)
+ * [Calculation Configuration](calculation-configuration)
+ * [Site Specification](site-specification)
+ * [Examples](/ghsc/nshmp/nshmp-haz-v2/-/tree/master/etc/examples)
+* [Hazard Model](hazard-model)
+ * [Model Structure](model-structure)
+ * [Model Files](model-files)
+ * [Source Types](source-types)
+ * [Magnitude Frequency Distributions (MFDs)](magnitude-frequency-distributions-mfds)
+ * [Rupture Scaling Relations](rupture-scaling-relations)
+ * [Ground Motion Models (GMMs)](ground-motion-models-gmms)
+* [USGS Models](usgs-models)
+ * [Model Editions](model-editions)
+ * [Logic Trees & Uncertainty](logic-trees-&-uncertainty)
+
+## Other Pages & References
+
+ * [nshmp-lib](/ghsc/nshmp/nshmp-lib): USGS hazard modeling library
+ * [Functional PSHA](functional-psha)
+ * [Probabilistic Seismic Hazard Analysis, a Primer [PDF]](http://www.opensha.org/sites/opensha.org/files/PSHA_Primer_v2_0.pdf) by Edward Field
+ * [An Introduction to Probabilistic Seismic Hazard Analysis [PDF]](http://web.stanford.edu/~bakerjw/Publications/Baker_(2015)_Intro_to_PSHA.pdf) by Jack Baker
+ * [License](../LICENSE.md)
diff --git a/docs/Logic-Trees-&-Uncertainty.md b/docs/Logic-Trees-&-Uncertainty.md
new file mode 100644
index 000000000..a49ec7032
--- /dev/null
+++ b/docs/Logic-Trees-&-Uncertainty.md
@@ -0,0 +1,125 @@
+# USGS Models: Logic Trees & Uncertainty
+
+The following page details the logic trees of epistemic uncertainty considered in NSHMs supported
+by *nshmp-haz*. Logic trees are represented in a NSHM using files ending in `-tree.json`
+([example]()).
+
+[[_TOC_]]
+
+## Terminology
+
+**Epistemic Uncertainty**: Uncertainty due to limited data and knowledge. Characterized by
+alternative models.
+**Aleatory Variability**: Inherent uncertainty due to random variability.
+
+## Stable Crust Ground Motion Models
+
+| Description | 2008 | 2014 | 2018 |
+|:----------- |:----- |:---- |:---- |
+| CEUS | __0.1__ : AB_06 (140 bar)<br />__0.1__ : AB_06 (200 bar)<br />__0.1__ : CAMPBELL_03<br />__0.1__ : FRANKEL_96<br />__0.1__ : SILVA_02<br />__0.2__ : SOMERVILLE_01<br />__0.2__ : TORO_97<br />__0.1__ : TP_05 | __0.22__ : AB_06'<br />__0.08__ : ATKINSON_08'<br />__0.11__ : CAMPBELL_03<br />__0.06__ : FRANKEL_96<br />__0.15__ : PEZESHK_11<br />__0.06__ : SILVA_02<br />__0.10__ : SOMERVILLE_01<br />__0.11__ : TORO_97<br />__0.11__ : TP_05 | __0.667__ : NGA_EAST_USGS (17)<br />__0.333__ : NGA_EAST_SEEDS (14)<br />(common aleatory variability) |
+| Sigma Epistemic | _(none)_ | _(no change)_ | __0.2__ : USGS Panel<br />__0.8__ : EPRI |
+| Site Aleatory | _(none)_ | _(no change)_ | __0.185, 0.63, 0.185__ : Site ± σ |
+
+---
+
+## Active Crustal Ground Motion Models
+
+| Description | 2008 | 2014 | 2018 |
+|:----------- |:----- |:---- |:---- |
+| WUS | __0.3333__ : BA_08<br />__0.3333__ : CB_08<br />__0.3334__ : CY_08 | __0.22__ : ASK_14<br />__0.22__ : BSSA_14<br />__0.22__ : CB_14<br />__0.22__ : CY_14<br />__0.22__ : IDRISS_14 | __0.25__ : ASK_14<br />__0.25__ : BSSA_14<br />__0.25__ : CB_14<br />__0.25__ : CY_14 |
+| Mean Epistemic | NGA-West1 (M,R)<br />__0.185__ : epi+<br />__0.630__ : off<br />__0.185__ : epi- | NGA-West2 (M,R)<br />__0.185__ : epi+<br />__0.630__ : off<br />__0.185__ : epi- | _(no change)_ |
+
+---
+
+## Subduction Ground Motion Models
+
+| Description | 2008 | 2014 | 2018 |
+|:----------- |:----- |:---- |:---- |
+| Cascadia<br />(interface) | __0.25__ : AB_03 (global)<br />__0.25__ : YOUNGS_97<br />__0.50__ : ZHAO_06 | __0.1__ : AB_03 (global)<br />__0.3__ : AM_09<br />__0.3__ : BCHYDRO_12<br />__0.3__ : ZHAO_06 | __0.3333__ : AM_09<br />__0.3334__ : BCHYDRO_12<br />__0.3333__ : ZHAO_06 |
+| Cascadia<br />(slab) | __0.25__ : AB_03 (global)<br />__0.25__ : AB_03 (cascadia)<br />__0.50__ : YOUNGS_97 | __0.1665__ : AB_03 (global, mod)<br />__0.1665__ : AB_03 (cascadia, mod)<br />__0.3330__ : BCHYDRO_12<br />__0.3340__ : ZHAO_06 | __0.5__ : BCHYDRO_12<br />__0.5__ : ZHAO_06 |
+
+---
+
+## Fault Source Model (CEUS)
+
+| Model | Description | 2008 | 2014 | 2018 |
+|:----- |:----------- |:---- |:---- |:---- |
+| Deformation | | __1.0__ : GEO | __0.1__ : BIRD<br />__0.8__ : GEO<br />__0.1__ : ZENG | _(no change)_ |
+| Rupture | | __0.5__ : Full<br /> __0.5__ : Partial | _(no change)_ | _(no change)_ |
+| Magnitude Scaling | | __1.0__ : Somerville-01 (area) | _(no change)_ | _(no change)_ |
+| Maximum M¹ | Partial: epistemic | __0.2, 0.6, 0.2__ : M ± 0.2 | _(no change)_ | _(no change)_ |
+| | Full : epistemic | __0.2, 0.6, 0.2__ : M ± 0.2 | _(no change)_ | _(no change)_ |
+| | Full : aleatory | M ± 0.24 (±2σ normal PDF) | _(no change)_ | _(no change)_ |
+
+¹ There are a very limited number of fault sources in CEUS
+
+---
+
+## Fault Source Model (WUS)
+
+| Model | Description | 2008 | 2014 | 2018 |
+|:----- |:----------- |:---- |:---- |:---- |
+| Deformation | | __1.0__ : GEO | __0.1__ : BIRD<br />__0.8__ : GEO<br />__0.1__ : ZENG | _(no change)_ |
+| Rupture | Partial | __0.333__ : IMW, __0.5__ : PNW | _(no change)_ | _(no change)_ |
+| | Full | __0.667__ : IMW, __0.5__ : PNW | _(no change)_ | _(no change)_ |
+| Magnitude Scaling | | __1.0__ : WC_94 (length) | _(no change)_ | _(no change)_ |
+| Maximum M | Partial: epistemic | __0.2, 0.6, 0.2__ : M ± 0.2 | _(no change)_ | _(no change)_ |
+| | Full : epistemic | __0.2, 0.6, 0.2__ : M ± 0.2 | _(no change)_ | _(no change)_ |
+| | Full : aleatory | M ± 0.24 (±2σ normal PDF) | _(no change)_ | _(no change)_ |
+| Dip | Reverse & Strike-Slip | __1.0__ : assigned | _(no change)_ | _(no change)_ |
+| | Normal | __0.2, 0.6, 0.2__ : 50 ± 10° | __0.2, 0.6, 0.2__ : 50±15° | _(no change)_ |
+
+---
+
+## Grid Source Model
+
+| Model | Description | 2008 | 2014 | 2018 |
+|:----- |:----------- |:---- |:---- |:---- |
+| Maximum M | WUS (exceptions) | __1.0__ : 7.0 | __0.9__ : 7.5 (truncated)<br />__0.1__ : 8.0 (tapered) | _(no change)_ |
+| | CEUS (craton) | __0.1__ : 6.6<br />__0.2__ : 6.8<br />__0.5__ : 7.0<br />__0.2__ : 7.2 | __0.2__ : 6.5<br />__0.5__ : 7.0<br />__0.2__ : 7.5<br />__0.1__ : 8.0 | _(no change)_ |
+| Smoothing | | __1.0__ : Fixed |__0.4__ : Adaptive<br />__0.6__ : Fixed | _(no change)_ |
+| Magnitude Scaling | CEUS & WUS | __1.0__ : WC_94 (length) | _(no change)_ | _(no change)_ |
+| Focal Mechanisms | Spatially Varying | __1.0__ : assigned | _(no change)_ | _(no change)_ |
+| Depth (zTor) | WUS, M < 6.5 | __1.0__ : 5.0 km | _(no change)_ | _(no change)_ |
+| | WUS, M ≥ 6.5 | __1.0__ : 1.0 km | _(no change)_ | _(no change)_ |
+| | CEUS, All M | __1.0__ : 5.0 km | _(no change)_ | _(no change)_ |
+
+---
+
+## Fault Source Model (CA, UCERF3)
+
+| Model | 2014 | 2018 |
+|:----- |:---- |:---- |
+| Fault | __0.5__ : FM3.1<br /> __0.5__ : FM3.2 | _(no change)_ |
+| Deformation | __0.1__ : ABM<br />__0.3__ : BIRD<br />__0.3__ : GEO<br />__0.3__ : ZENG | _(no change)_ |
+| Scaling Relationship<br />(mag-area & slip-length)| __0.2__ : ELLS_B<br />__0.2__ : ELLS_B (sqrt-L)<br />__0.2__ : HB_08<br />__0.2__ : SHAW_09<br />__0.2__ : SHAW_09 (csd) | _(no change)_ |
+| Slip Distribution | __0.5__ : Tapered<br />__0.5__ : Boxcar | _(no change)_ |
+| M ≥ 5 rate (yrâ»Â¹) | __0.1__ : 6.5<br />__0.6__ : 7.9<br />__0.3__ : 9.6 | _(no change)_ |
+| Inversion Constraint | __1.0__ : UCERF2 (CH) | _(no change)_ |
+| Fault Mo Rate | __1.0__ : off | _(no change)_ |
+
+---
+
+## Grid Source Model (CA, UCERF3)
+
+| Model | 2014 | 2018 |
+|:----- |:---- |:---- |
+| Grid: Maximum M | __0.1__ : 7.3<br />__0.8__ : 7.6<br />__0.1__ : 7.9 | _(no change)_ |
+| Grid: Smoothing | __0.5__ : Adaptive<br />__0.5__ : Fixed | _(no change)_ |
+| Grid: Focal Mechanisms | __1.0__ : assigned | _(no change)_ |
+| Magnitude Scaling | __1.0__ : WC_94 (length) | _(no change)_ |
+
+---
+
+## Subduction seismic source model
+
+| Model | 2008 | 2014 | 2018 |
+|:----- |:---- |:---- |:---- |
+| Rupture | __0.67__ : Full<br />__0.33__ : Partial | __1.0__ : Full<br />__0.5__ : Partial (segmented)<br />__0.5__ : Partial (unsegmented) | _(no change)_ |
+| Magnitude Scaling | __1.0__ : Youngs et al. (length) | __0.334__ : Strasser et al. (2010)<br />__0.333__ : Murotani et al. (2008)<br />__0.333__ : Papazachos et al. (2004) | _(no change)_ |
+| Magnitude Uncertainty | __0.2, 0.6, 0.2__ : M±0.2 | _(none)_ | _(no change)_ |
+| Depth | __0.5__ : Base<br />__0.2__ : Bottom<br />__0.2__ : Middle<br />__0.1__ : Top | __0.3__ : Bottom<br />__0.5__ : Middle<br />__0.2__ : Top | _(no change)_ |
+| Slab: Maximum M | __1.0__ : 7.2 | __0.9__ : 7.5<br />__0.1__ : 8.0 | _(no change)_ |
+
+* Full: a.k.a. 'characteristic'
+* Partial: a.k.a. 'Gutenberg-Richter' or 'floating'
diff --git a/docs/Magnitude-Frequency-Distributions.md b/docs/Magnitude-Frequency-Distributions.md
new file mode 100644
index 000000000..c51b4d288
--- /dev/null
+++ b/docs/Magnitude-Frequency-Distributions.md
@@ -0,0 +1,239 @@
+# Magnitude-Frequency Distributions (MFDs)
+
+An earthquake source requires a description of the sizes and rates of all earthquakes it is
+capable of generating, otherwise known as a magnitude-frequency distribution (MFD). The different
+types of MFDs supported in a hazard model are described below. Unless otherwise noted, all the
+members listed in the JSON examples below are required.
+
+[[_TOC_]]
+
+MFD types:
+ * [Single](#single-magnitude-mfd)
+ * [Gutenberg-Richter](#gutenberg-richter-mfd)
+ * [Tapered Gutenberg-Richter](#tapered-gutenberg-richter-mfd)
+ * [Incremental](#incremental-mfd)
+
+## Single
+
+A single MFD represents an earthquake of a specific magnitude size and rate. The `rate` member
+is optional when a logic tree of rates is also present in a model. Example:
+
+```json
+ {
+ "type": "SINGLE",
+ "m": 7.0,
+ "rate": 0.0001
+ }
+```
+
+## Gutenberg–Richter
+
+A [Gutenberg–Richter](http://en.wikipedia.org/wiki/Gutenberg–Richter_law) MFD represents a range
+of evenly discretized magnitude events with systematically varying rates. Specifically, a
+Gutneberg–Richter MFD is a doubly-truncated exponential distribution with limits at `mMin` and
+`mMax`, a y-intercept of `a`, and a slope of `b`. The `a`-value member is optional when a logic
+tree of rates for a source is also present in a model. Example:
+
+```json
+ {
+ "type": "GR",
+ "a": 1.0,
+ "b": 0.8,
+ "mMin": 6.55,
+ "mMax": 6.95,
+ "Δm": 0.1
+ }
+```
+
+## Tapered Gutenberg–Richter
+
+A [tapered Gutenberg-Richter](http://scec.ess.ucla.edu/~ykagan/moms_index.html) MFD is similar to
+Gutenberg-Richter, above, but with an exponential taper applied with a corner magnitude of `mCut`.
+The `a`-value member is optional when a logic tree of rates for a source is also present in a
+model. Example:
+
+```json
+ {
+ "type": "GR_TAPER",
+ "a": 1.0,
+ "b": 0.8,
+ "mCut": 6.5,
+ "mMin": 5.0,
+ "mMax": 7.0,
+ "Δm": 0.1
+ }
+```
+
+## Incremental
+
+A general purpose MFD that represents defined by explicit arrays of magnitudes and rates. Example:
+
+```json
+ {
+ "type": "INCR",
+ "magnitudes": [5.05, 5.15, ...],
+ "rates": [1.0e-2, 0.9e-2, ...]
+ }
+```
+
+## MFD Construction
+
+Construction of MFDs from their declaration in a tree _may_ also depend on the following files:
+
+**mfd-map.json:** If an `mfd-tree` value is a string, then that value must map to an actual logic
+tree in a `mfd-map.json` file that is typically located high in the source model heirarchy. For
+example:
+
+```json
+{
+ "mfd-tree-1": [
+ { "id": "M1","weight": 0.5, "value": { "type": "SINGLE", "m": 7.0}},
+ { "id": "M2","weight": 0.5, "value": { "type": "SINGLE", "m": 7.5}}
+ ],
+ "mfd-tree-2": [
+ { "id": "M1","weight": 0.5, "value": { "type": "SINGLE", "m": 7.3}},
+ { "id": "M2","weight": 0.5, "value": { "type": "SINGLE", "m": 7.8}}
+ ],
+}
+```
+
+**mfd-config.json:**
+
+
+MFD confguration files:
+ * mfd-map.json
+ * mfd-config.json
+ * rate-tree.json
+ * Rate files (*.csv)
+
+For instance, the final MFDs used in a hazard may be modified by an epistemic or aleatory uncertainty model specified in `mfd-config.json`. Single and Gutenberg-Richter MFDs that do not have their `rate` or `a`-value members defined rely on the presence of a `rate-tree.json` file. A rate-tree defines a logic tree of rates or pointers to CSV rate files with spatially varying rate data.
+
+#### `mfd-map.json`
+
+A mfd-map defines multiple mfd-trees common to multiple branches of a source-tree.
+
+
+
+#### `mfd-config.json`
+
+Additional uncertainty in MFDs is often considered when building hazard models and is defined in a `mfd-config.json` file. Application of uncertainty models is MFD type-dependent. The `epistemic-tree` member, if non-null, is used to create 3-branches for single and Gutenberg-Richter MFDs. For a single MFD, a moment-balanced three-point distribution of magnitudes (± 0.2 magnitude units) is created. For a Gutenberg-Richter MFD, three maximum magnidue branches are created, also moment-balanced. The `aleatory-properties` member is only applicable to single MFDs and may be applied on top of an epistemic-tree. In the example below, `aleatory-properties` defines an eleven-point, moment-balanced normal distribution with a width of ±2σ of magnitudes about a central magnitude. If no additional uncertainty model is desired, `epistemic-tree` and `aleatory-properties` should be set to null.
+
+TODO is aleatory uncertainty in MFD ALWAYS moment-balanced???
+
+```json
+{
+ "epistemic-tree": [
+ { "id": "+epi", "weight": 0.2, "value": -0.2 },
+ { "id": "----", "weight": 0.6, "value": 0.0 },
+ { "id": "-epi", "weight": 0.2, "value": 0.2 }
+ ],
+ "aleatory-properties": {
+ "count": 11,
+ "momentBalanced": true,
+ "σSize": 2,
+ "σ": 0.12
+ },
+ "minimum-magnitude": 6.5
+}
+```
+
+#### `rate-tree.json`
+
+A rate-tree defines each branch `value` in years (recurrence or return period):
+
+```json
+[
+ {
+ "id": "R1",
+ "weight": 0.2,
+ "value" : 10000
+ },
+ {
+ "id": "R2",
+ "weight": 0.8,
+ "value" : 2000
+ }
+]
+```
+
+or with pointers to rate files, in the case of grid sources:
+
+```json
+[
+ {
+ "id": "fixed",
+ "weight": 0.6,
+ "value" : "fixed.csv"
+ },
+ {
+ "id": "adaptive",
+ "weight": 0.4,
+ "value" : "adaptive.csv"
+ }
+]
+```
+
+**mfd-config.json:** Controls properties of the MFD and possible additional epistemic or aleatory
+uncertainty. For example:
+
+```json
+{
+ "epistemic-tree": [
+ { "id": "+uâ‚‘", "weight": 0.2, "value": -0.2 },
+ { "id": "~uâ‚‘", "weight": 0.6, "value": 0.0 },
+ { "id": "-uâ‚‘", "weight": 0.2, "value": 0.2 }
+ ],
+ "aleatory-properties": {
+ "size": 11,
+ "nσ": 2,
+ "σ": 0.12
+ },
+ "minimum-magnitude": 6.5,
+ "nshm-bin-model": false
+}
+```
+
+**rate-tree.json:** Defines each branch `value` in annual rate (1 / return period in years).
+For example:
+
+```json
+[
+ {
+ "id": "R1",
+ "weight": 0.2,
+ "value" : 0.002
+ },
+ {
+ "id": "R2",
+ "weight": 0.8,
+ "value" : 0.05
+ }
+]
+```
+
+
+
+From Model Files:
+
+#### Magnitude Frequency Distributions (MFDs)
+
+`mfd-tree`, `mfd-map.json`, `mfd-config.json`, and `rate-tree.json`
+
+A `mfd-tree` property is common to all source types and defines a logic tree of magnitude frequency distributions (MFDs). The `mfd-tree` element may be an array of mfd branches defined inline or a string reference to a top-level member of an `mfd-map.json` that contains one or more mfd-trees shared across a source-tree. The branches of a mfd-tree commonly have the generic ID's: `[M1, M2, M3, ...]` to support mfd-tree matching across source-tree branches.
+
+```json
+"mfd-tree": [
+ { "id": "M1", "weight": 0.3, "value": { "type": "SINGLE", "m": 6.8, "rate": 0.001 }},
+ { "id": "M2", "weight": 0.3, "value": { "type": "SINGLE", "m": 7.0, "rate": 0.001 }},
+ { "id": "M3", "weight": 0.3, "value": { "type": "SINGLE", "m": 7.2, "rate": 0.001 }},
+ { "id": "M4", "weight": 0.1, "value": { "type": "SINGLE", "m": 7.4, "rate": 0.001 }}
+]
+```
+
+How MFDs are actually built depends on the settings in a `mfd-config.json` file and rates For more details on MFDs and their configuration see the [magnitude frequency distributions](magnitude-frequency-distributions) section.
+
+An `mfd-config.json` is currently only required for finite fault sources. It can be located anywhere in the file heirarchy and may be overridden in nested directories.
+
+
+Depending on the types of MFDs being modeled, a rate file may contain Gutenberg-Richter a-values or magnitude-specific rates. The branches of a rate-tree commonly have the generic ID's: `[R1, R2, R3, ...]` to support matching rate-trees across source-tree branches.
+
diff --git a/docs/Model Editions.md b/docs/Model Editions.md
new file mode 100644
index 000000000..94cf0cded
--- /dev/null
+++ b/docs/Model Editions.md
@@ -0,0 +1,100 @@
+# USGS Models: Editions
+
+USGS hazard models are created and updated in response to user needs. In some cases a model is
+updated in response to cyclic updates to the U.S. Building Code. In other cases, enough time has
+passed that there have been significant advancements in the science, availability of relevant
+data, or modeling procedures that warrant a model update. Every model the USGS produces is
+associated with a USGS Open-File report or refereed journal article and supporting datasets.
+However, layered on top of any given model release are bug-fixes and model improvements.
+
+With the update to a new codebase, [nshmp-haz](https://github.com/usgs/nshmp-haz), the NSHMP has
+adopted [semantic versioning](http://semver.org) to keep track of different hazard models. For
+any given model region, the first number (or major version) corresponds to a particular release
+or update year. For example, we consider the initial
+[1996 conterminous U.S. NSHM](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#1996)
+to be v1.0.0. The second number (or minor version) reflects updates to a particular release that
+likely causes small changes to hazard values. The third number reflects non-hazard altering
+changes; for instance, a change to the model file format that has no consequence on computed
+hazard.
+
+The USGS NSHMP is committed to supporting current and prior model releases in any given region
+via web services. The table below provides a summary of all NSHM releases and their corresponding
+version numbers.
+
+Region | Year | Version | Static | Dynamic | Notes |
+-------|:----:|:-------:|:------:|:-------:|-------|
+Conterminous U.S. | [2014](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2014) | [v4.2.0](https://github.com/usgs/nshmp-model-cous-2014/releases/tag/v4.2.0)<sup>†</sup> | |:small_blue_diamond:| |
+Conterminous U.S. | [2014](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2014) | [v4.1.4](https://github.com/usgs/nshmp-model-cous-2014/releases/tag/v4.1.4)<sup>†</sup> | |:small_blue_diamond:| |
+Conterminous U.S. | [2014](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2014) | [v4.0.0](https://github.com/usgs/nshmp-haz-fortran/releases/tag/nshm2014r1) |:small_blue_diamond:| | ASCE7-16 |
+Conterminous U.S. | [2008](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2008) | v3.3.3 | |:small_blue_diamond:| |
+Conterminous U.S. | [2008](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2008) | [v3.2.0](https://github.com/usgs/nshmp-haz-fortran/releases/tag/nshm2008r3) |:small_blue_diamond:| | |
+Conterminous U.S. | [2008](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2008) | v3.1.0 |:small_blue_diamond:| | ASCE7-10 |
+Conterminous U.S. | [2008](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2008) | v3.0.0 | | | |
+Conterminous U.S. | [2002](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2002) | v2.0.0 | | | |
+Conterminous U.S. | [1996](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#1996) | v1.0.0 | | | |
+Alaska | [2007](https://earthquake.usgs.gov/hazards/hazmaps/ak/index.php#2007) | v2.1.0 | |:small_blue_diamond:| |
+Alaska | [2007](https://earthquake.usgs.gov/hazards/hazmaps/ak/index.php#2007) | v2.0.0 |:small_blue_diamond:| | ASCE7-10 |
+Alaska | [1999](https://earthquake.usgs.gov/hazards/hazmaps/ak/index.php#1999) | v1.0.0 | | | |
+American Samoa | [2012](https://earthquake.usgs.gov/hazards/hazmaps/islands.php#samoapacific) | v1.0.0 | | | |
+Guam | [2012](https://pubs.usgs.gov/of/2012/1015/) | v1.0.0 | | | |
+Hawaii | [2018](https://earthquake.usgs.gov/hazards/hazmaps/islands.php#hi) | v2.0.0 | | TBD | |
+Hawaii | [1998](https://earthquake.usgs.gov/hazards/hazmaps/islands.php#hi) | v1.1.0 | | TBD | |
+Hawaii | [1998](https://earthquake.usgs.gov/hazards/hazmaps/islands.php#hi) | v1.0.0 |:small_blue_diamond:| | ASCE7-10 |
+Puerto Rico & <br/> U.S. Virgin Islands | [2003](https://earthquake.usgs.gov/hazards/hazmaps/islands.php#prvi) | v1.0.0 | | | |
+
+<sup>†</sup> __Note on the 2014 Conterminous U.S. NSHM:__ Initial publication of the
+[2014 model](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2014) included
+data to support updates to the U.S. Building Code, specifically hazard curves for peak ground
+acceleration (PGA), and 0.2 and 1.0 second spectral accelerations, all at a BC boundary site
+class with Vs30 = 760 m/s. Some time later, the model was deployed to the Unified Hazard Tool
+(UHT) and included support in the Wester U.S. for calculations at sites other than Vs30 = 760 m/s,
+consistent with dynamic calculations using the 2008 model. Subsequently, we updated the 2014
+model with [addional periods and site classes](https://pubs.er.usgs.gov/publication/ofr20181111).
+Doing so required dropping several ground motion models (GMMs) and a redistribution of logic-tree
+weights. Specifically, the Idriss (2014) model is inappropriate for use at soft soil sites and
+the Atkinson & Boore (2003) model does not support long periods (see the
+[open-file report](https://pubs.er.usgs.gov/publication/ofr20181111) for more information).
+Moving forward, we will continue to include the original dynamic version of the 2014 model
+(v4.1.4) in the UHT. However, we recommend that users consider the updated model (4.2.0).
+
+### Static vs. Dynamic
+
+Historically, the USGS NSHMP has produced static datasets of hazard curves that accompany the
+'official' release or update to a model. In the context of providing interactive web services,
+such static datasets can be quickly retreived and provide most users with the data they seek.
+More complex analyses, such as deaggregations, require that a complete hazard calculation be
+performed on demand. Historically, USGS deaggregation services were provided for particular model
+years and regions, each located at a unique web address and supported by a unique codebase.
+However, it has proven too difficult to maintain numerous isolated services, and we therefore
+developed a single codebase that supports all current and prior models.
+
+Moreover, as time goes by, there may be more customization options we want to expose to users.
+However, with each additional level of customization, it quickly becomes too difficult to produce
+and version corresponding static datasets. We therefore identify model versions that support
+deaggregations and other calculations as 'dynamic'. At present, only the most current versions
+of a particular model region and year are supported via 'dynamic' calculations.
+
+In practice, this leads to results produced by 'dynamic' caluculations being somewhat different
+than those stored in static datasets of prior model minor versions, although usually not by much.
+The release notes for each model version detail the changes that give rise to changes in hazard
+between between versions. There are also differences that arise from different modeling
+assumptions between past and current codebases that are detailed below.
+
+It is important for users to know which edition they should be using. For instance if one is
+bound to use those values adopted by the U.S. building code, one of the editions marked `ASCE7-*`
+is probably most appropriate. However, if one is bound to use the most up to date source model,
+one of the dynamic editions is likely better.
+
+Dynamic editions are supported through web-services provided by the `nshmp-haz-ws` library
+(this repository). Static editions are supported via a separate set of services. Both are
+documented on the [web services](web-services) page.
+
+### Region specific changes
+
+Changes between editions in model regions are documented in the release notes of the individual
+model repositories.
+
+* [Conterminous US (2014)](/usgs/nshmp-model-cous-2014/wiki)
+* [Conterminous US (2008)](/usgs/nshmp-model-cous-2008/wiki)
+* [Alaska (2007)](/usgs/nshmp-model-ak-2007/wiki)
+
diff --git a/docs/Model-Files.md b/docs/Model-Files.md
new file mode 100644
index 000000000..267950cd9
--- /dev/null
+++ b/docs/Model-Files.md
@@ -0,0 +1,186 @@
+# Model Files
+
+A variety of logic tree, configuration, and data files that are common to all models and source
+types are described below and on related pages for specific model components, for example, ground
+motion models (GMMs) or magnitude-frequency distributions (MFDs).
+
+[[_TOC_]]
+
+## Model and Calculation Configuration
+
+**model-info.json:** Required model identifying metadata. Currently the model name and
+definitions of Vs30 values for each NEHRP site class that were used when computing design ground
+motions from the model.
+
+```json
+{
+ "name": "NSHM Conterminous U.S. 2018",
+ "site-class-vs30": {
+ "AB": 1500,
+ "B": 1080,
+ "BC": 760,
+ "C": 530,
+ "CD": 365,
+ "D": 260,
+ "DE": 185,
+ "E": 150
+ }
+}
+```
+
+**calc-config.json:** Optional calculation configuration file specifies the default
+calculation settings used for a NSHM. This file overrides any built in default values. See
+the [calculation configuration](calculation-configuration) page for more details.
+
+## Logic Trees
+
+Any file or JSON member name containing `-tree` implies that the file contents or member value
+will be an array of logic tree branches. Branches are defined with an `id`, `weight`, and `value`.
+Depending on context, value can be a number, string, or object. For example:
+
+ ```json
+ [
+ {
+ "id": "string",
+ "value": "number | string | object",
+ "weight": 0.4
+ }, {
+ "id": "string",
+ "value": "number | string | object",
+ "weight": 0.6
+ }
+]
+```
+
+If the `value` member is absent, then the branch `id` is also the `value`. Logic tree weights must
+sum to one. Examples of logic trees present in a hazard model are described below.
+
+### Source Model Logic Trees
+
+**source-tree.json:** Defines a single logic tree branching point where each branch `value` points
+to a subdirectory of nested branches. Source-tree weights are used to scale hazard curves when
+computing mean hazard and for source event-set selection. When loading a model, a source-tree
+governs all subsequent processing of nested directories. Only those resources required by the tree
+or its children will be processed; any standalone sources will be ignored. For example:
+
+```json
+[
+ {
+ "id": "segmented",
+ "weight": 0.5
+ },
+ {
+ "id": "unsegmented",
+ "weight": 0.5
+ }
+]
+```
+
+**source-group.json:** A specialized form of logic tree that describes model branches that are
+additivd and therefore does not include weights. Examples from the NSHM for the Conterminous U.S.
+NSHM include the Cascadia segmented partial-rupture models and the New Madrid 1500-yr cluster
+branches. The branch objects in a source group _may_ include an optional `scale` member that can
+be used to impose a probability of occurrence or other scaling requred by a NSHM. If absent, the
+`scale` value is one.
+
+```json
+[
+ {
+ "id": "all",
+ "scale": 0.2
+ },
+ {
+ "id": "center-south",
+ "scale": 1.5
+ }
+]
+```
+
+### GMM Logic Trees
+
+**gmm-tree.json:** Defines the logic tree of ground motion models to use in each tectonic setting.
+For example:
+
+```json
+[
+ { "id": "ASK_14", "weight": 0.25 },
+ { "id": "BSSA_14", "weight": 0.25 },
+ { "id": "CB_14", "weight": 0.25 },
+ { "id": "CY_14", "weight": 0.25 }
+]
+```
+
+See the [ground motion models](ground-motion-models) page for details on GMMs supported in
+_nshmp-haz_ and the related `gmm-config.json` files that governs GMM behavior.
+
+### MFD Logic Trees
+
+MFD logic trees are typically defined as JSON members nested in other files. For example:
+
+```json
+"mfd-tree": [
+ { "id": "M1", "weight": 0.3, "value": { "type": "SINGLE", "m": 6.8, "rate": 0.001 }},
+ { "id": "M2", "weight": 0.3, "value": { "type": "SINGLE", "m": 7.0, "rate": 0.001 }},
+ { "id": "M3", "weight": 0.3, "value": { "type": "SINGLE", "m": 7.2, "rate": 0.001 }},
+ { "id": "M4", "weight": 0.1, "value": { "type": "SINGLE", "m": 7.4, "rate": 0.001 }}
+]
+```
+
+An `mfd-tree` may be included as a `properties` member of a GeoJSON feature or as a member of a
+`rupture-set.json` file. In both cases the tree may alternatively be identified with a string, in
+which case the `mfd-tree` will be pulled from the collection of trees defined in a `mfd-map.json`
+file. A `mfd-map.json` file is typicaly located high in the source tree heirarchy and faciltates
+using the same MFDs on multiple branches of a source tree.
+
+How MFDs are intialized (or realized) depends on the presence and contents of `mfd-config.json` and
+`rate-tree.json` files. See the
+[magnitude frequency distributions](magnitude-frequency-distributions) page for details on these
+files and the types of MFDs supported in _nshmp-haz_.
+
+## Rupture Sets
+
+A `rupture-set` is the terminal file of a source-tree branch and defines the fault sections and
+MFD's required to intialize a source.
+
+**rupture-set.json**
+
+```json
+{
+ "name": "New Madrid - USGS (center)",
+ "id": 3023,
+ "sections": [3020, 3021, 3022],
+ "mfd-tree": "usgs-hi-mag"
+}
+```
+
+In the example above, one set of New Madrid ruptures is assigned the specified numeric `id`. The
+fault geometry of the rupture-set is constructed by stitching the specified fault `sections`
+together, and earthquake magnitudes and rates are governed by the specified `mfd-tree`. In this
+case, `mfd-tree` points to a named tree that will be present in an `mfd-map.json` accompanying
+the source-tree. The `sections` member may be absent. In this case, the `id` of the rupture-set
+is the same as the single, associated fault section.
+
+**cluster-set.json**
+
+Fault sources also support cluster models where the total hazard is computed from the probability
+of exceeding some ground motion level is conditioned on the occurrence of 2 or more, roughly
+contemporaneous events. A cluster-set is composed of an array of rupture-sets.
+
+```json
+{
+ "name": "New Madrid - USGS (center, center-south)",
+ "id": 3025,
+ "rupture-sets": [
+ {
+ "name": "USGS (center, center)",
+ "id": 3021,
+ "mfd-tree": "usgs-hi-mag"
+ },
+ {
+ "name": "USGS (center, south)",
+ "id": 3022,
+ "mfd-tree": "usgs-hi-mag"
+ }
+ ]
+}
+```
diff --git a/docs/Model-Structure.md b/docs/Model-Structure.md
new file mode 100644
index 000000000..4ca92befd
--- /dev/null
+++ b/docs/Model-Structure.md
@@ -0,0 +1,195 @@
+# Model Structure
+
+Earthquake source models are specified using [JSON](https://www.json.org),
+[GeoJSON](https://geojson.org), and CSV files. The files in a model directory tree are largely
+self describing and represent logic trees and other relationships between source model ingredients
+(JSON), source geometry (GeoJSON features), and earthquake rate data (CSV). JSON is well-suited
+for representing model data and relationships and is supported in most programming languages.
+
+[[_TOC_]]
+
+## Directory Structure
+
+Earthquake source files are organized by tectonic setting: `active-crust`, `stable-crust`,
+`subduction-interface`, `subduction-slab`, and `volcanic` with the two crustal and the volcanic
+settings supporting the nested source types: `fault-sources`, `grid-sources`, and `zone-sources`.
+The `volcanic` tectonic setting also supports `decollement-sources`.
+
+The root of a model must include `model-info.json` and _may_ include a `calc-config.json` that
+specifies any custom default [calculation configuration](calculation-configuration) settings
+for the model. Top level tectonic setting directories must include `gmm-tree.json` and
+`gmm-config.json` files. Source directories are loaded recursively, permitting configuration files
+deeper in the heirarchy to override those defined higher in the heirarchy, as needed and as
+specified for each source type. Nested directories support associations between groups of sources,
+their configuration and initialization, and ground motion models. If there are a large number of
+sources in a model, sources are typically further organized by region or other grouping. Example
+model top-level directory tree:
+
+```text
+model-directory/
+ ├─ model-info.json (required)
+ ├─ calc-config.json (optional, overrides defaults)
+ │
+ ├─ active-crust/
+ │ ├─ gmm-config.json (required, can override)
+ │ ├─ gmm-tree.json (required, can override)
+ │ │
+ │ ├─ fault-sources/
+ │ │ └─ ...
+ │ │
+ │ ├─ grid-sources/
+ │ │ └─ ...
+ │ │
+ │ └─ zone-sources/
+ │ └─ ...
+ │
+ ├─ stable-crust/... Same structure as 'active-crust'
+ │ └─ ...
+ │
+ ├─ subduction-interface/ Similar structure to 'fault-sources'
+ │ └─ ...
+ │
+ └─ subduction-slab/ Similar structure to 'grid-sources'
+ └─ ...
+```
+
+The following sections describe each source type, associated configuration and source definition
+files, and any other requirements.
+
+## Crustal Finite Fault Sources
+
+Finite fault sources may either be defined as a single source (commonly with associated logic
+trees of MFDs, slip rates, or dip variations) or a more complex logic tree of source model
+variants. GeoJSON feature files define fault sections using a `LineString` representing the
+surface trace of the section. The coordinate order of the trace must adhere to the U.S. structural
+geology right-hand rule.
+
+```text
+fault-sources/
+ ├─ fault-config.json (required, can override)
+ ├─ mfd-config.json (required, can override)
+ ├─ mfd-map.json (optional) Map of shared mfd-trees
+ │
+ ├─ single-fault-sources/
+ │ ├─ source-1.geojson
+ │ ├─ source-2.geojson
+ │ └─ nested-sources/
+ │ └─ ...
+ │
+ └─ tree-based-fault-source/ Nested directories may have any name
+ ├─ source-tree.json Source logic tree; when present, governs
+ │ subsequent processing; includes pointers
+ │ to branch directories below
+ │
+ ├─ features/ (required) Directory of fault features
+ │ ├─ section-1.geojson
+ │ ├─ section-2.geojson
+ │ └─ ...
+ │
+ ├─ branch-1/
+ │ └─ rupture-set.json Fault source logic tree branching always
+ │ ends at a 'rupture-set'
+ └─ branch-2/
+ ├─ source-tree.json
+ ├─ branch-3/
+ └─ branch-4/
+```
+
+See also: [Finite Fault Source Type](source-types#finite-fault-sources)
+
+## Crustal Grid Sources
+
+*TODO this isn't quite right, needs conus-2018 refactor for verification*
+
+Grid sources are based on smoothed seismicity or other spatially varying rate model and may be
+defined as either single source features, each within its own directory, or as more complex logic
+trees of source model variants. Grid sources are modeled as point sources of varying complexity.
+Multiple GeoJSON `Polygon`s may be used to accomodate spatial variations in source properties.
+
+```text
+grid-sources/
+ ├─ grid-config.json (required, can override)
+ ├─ mfd-map.json (optional) Map of shared mfd-trees
+ ├─ features/ (required) Directory of grid feature bounds
+ ├─ grid-data/ (required) Directory of all spatial PDFs
+ │
+ ├─ single-grid-source/
+ │ ├─ grid-source.geojson
+ │ └─ rate-tree.json Optional tree of rates
+ │
+ └─ tree-based-grid-source/
+ ├─ source-tree.json Source logic tree
+ │
+ ├─ branch-1/
+ │ └─ grid-source.geojson Grid source logic tree branching always
+ ├─ branch-2/ ends at a *.geojson file
+ │ └─ ...
+ └─ ...
+```
+
+See also: [Grid Source Type](source-types#grid-sources)
+
+## Crustal Zone (Area) Sources
+
+Zone sources specify a single rate that is distributed over a GeoJSON `Polygon` using point source
+rupture models. Presently, there is a 1:1 mapping of source zones to their associated rate files.
+*__Note:__ The rate file approach will be discouraged and/or deprecated in the near future in favor
+of dynamically computing rates over a zone from a single value or `rate-tree.json` when the loading
+a model.*
+
+```text
+zone-sources/
+ ├─ zone-config.json (required, can override)
+ ├─ mfd-config.json (required)
+ ├─ mfd-map.json (optional) Map of shared mfd-trees
+ │
+ ├─ single-zone-source/
+ │ ├─ zone-source.geojson
+ │ ├─ zone-source.csv (required) File of rate data (current)
+ │ └─ [rate-tree.json] (optional) Tree of rates (future)
+ │
+ └─ tree-based-zone-source/
+ ├─ source-tree.json Source logic tree
+ └─ branch-1/
+ ├─ zone-source.geojson Grid source branching ends at a *.geojson file
+ ├─ zone-source.csv (required) file of rate data (current)
+ └─ [rate-tree.json] (optional) tree of rates (future)
+```
+
+See also: [Zone Source Type](source-types#zone-sources)
+
+## Subduction Interface Sources
+
+Subduction interface sources are modeled in a similar manner as crustal fault sources; they may
+be a single source or a more complex logic tree of source model variants. GeoJSON feature files
+define interface sections using a `MultiLineString` of multple traces at increasing depths. The
+coordinate order of each trace must adhere to the U.S. structural geology right-hand rule.
+
+```text
+subduction-interface
+ ├─ gmm-config.json (required)
+ ├─ gmm-tree.json (required)
+ ├─ interface-config.json (required)
+ ├─ mfd-config.json (required)
+ └─ ...
+```
+
+See also: [Subduction Interface Source Type](source-types#subduction-interface-sources)
+
+## Subduction Intraslab Sources
+
+Subduction intraslab sources are modeled in a similar manner as crustal grid sources. Slab sources
+typically have spatially varying rates, but their depths also vary. In contrast to grid sources,
+rate files (`*.csv`) are stored adjacent to their corresponding feature file (`*.geojson`);
+_this may change in a future release_.
+
+```text
+subduction-slab
+ ├─ gmm-config.json (required)
+ ├─ gmm-tree.json (required)
+ ├─ slab-config.json (required)
+ ├─ mfd-config.json (required)
+ └─ ...
+```
+
+See also: [Subduction Intraslab Source Type](source-types#subduction-intraslab-sources)
diff --git a/docs/Rupture-Scaling-Relations.md b/docs/Rupture-Scaling-Relations.md
new file mode 100644
index 000000000..268648315
--- /dev/null
+++ b/docs/Rupture-Scaling-Relations.md
@@ -0,0 +1,70 @@
+# Rupture-Scaling Relations
+
+Rupture scaling models describe relationships between rupture geometry and magnitude. Such models
+are used in a NSHM to:
+* Compute an expected magnitude from a rupture geometry.
+* Compute the size (length or area) of a rupture from a magnitude.
+* Compute point-source distance corrections (optimization for unknown strike)
+
+Rupture scaling model implementations typically impose restrictions on rupture aspect ratio. For
+more details see the [rupture scaling implementation]() reference.
+
+## Magnitude-Scaling Relationships
+
+| Region | Reference | Tectonic Setting | Type |
+|:------------------ |:------------------------- |:------------ |:---------------- |
+| WellsCoppersmith-L | Wells & Coppersmith (1994) | active crust | magnitude-length |
+| EllsworthB | WGCEP (2002) | active crust | magnitude-area |
+| EllsworthB-SqrtL¹ | Shaw (2013b) | active crust | magnitude-area |
+| HanksBakun-08 | Hanks & Bakun (2008) | active crust | magnitude-area |
+| Shaw09mod | Shaw (2013a, 2013b) | active crust | magnitude-area |
+| Shaw09mod-CSD¹ | Shaw (2013a, 2013b) | active crust | magnitude-area |
+| Somerville-01 | Somerville et al. (2001) | stable crust | magnitude-area |
+| Strasser-10 | Strasser et al. (2010) | subduction | magnitude-length |
+| Murotani-08 | Murotani et al. (2008) | subduction | magnitude-length |
+| Papazachos-04 | Papazachos et al. (2004) | subduction | magnitude-length |
+| Youngs-97 | Youngs et al. (1997) | subduction | magnitude-length |
+
+
+¹ UCERF3 uses rupture scaling relationships to also balance slip rate when computing rupture
+rates. These models consider alternative slip-length scaling relations relative to the default
+computed from rupture area and moment; see Field et al. (2014) for details.
+
+² Also referred to as the 'Geomatrix' relation
+
+## References
+
+Hanks TC, and Bakun WH (2008) M- log A observations of recent large earthquakes. Bulletin of the
+Seismological Society of America 98(1): 490–494.
+
+Murotani S, Miyake H, Koketsu K (2008) Scaling of characterized slip models for plate-boundary
+earthquakes. Earth, Planets, and Space 60(?): 987–981.
+
+Papazachos BC, Scordilis EM, Panagiotopoulos DG, Papazachos CB, and Karakaisis GF (2004) Global
+relations between seismic fault parameters and moment magnitudes of earthquakes. Bulletin of the
+Geological Society of Greece 36(?): 1482–1489.
+
+Shaw BE (2013a) Earthquake surface slip-length data is fit by constant stress drop and is useful
+for seismic hazard analysis, Bulletin of the Seismological Society of America 103(2A): 876-893.
+
+Shaw BE (2013b) Appendix E: Evaluation of magnitude-scaling relationships and depth of rupture:
+Recommendation for UCERF3, U.S. Geol. Surv. Open-File Rept. 2013-1165-E, and California Geol.
+Surv. Special Rept. 228-E.
+
+Somerville P, Collins N, Abrahamson NA, Graves R, and Saikia C (2001) Ground motion attenuation
+relations for the Central and Eastern United States—Final report, June 30, 2001: Report to U.S.
+Geological Survey for award 99HQGR0098, 38 p.
+
+Strasser FO, Arango MC, and Bommer JJ (2010) Scaling of the source dimensions of interface and
+intraslab subduction-zone earthquakes with moment magnitude: Seismological Research Letters
+81(?): 941–950.
+
+Wells DL and Coppersmith KJ (1994) New empirical relationships among magnitude, rupture length,
+rupture width, and surface displacements: Bulletin of the Seismological Society of America,
+84(?): 974–1002.
+
+Working Group on California Earthquake Probabilities (WGCEP) (2003). Earthquake probabilities in
+the San Francisco Bay region: 2002– 2031, U.S. Geol. Surv. Open-File Report 2003-214.
+
+Youngs RR, Chiou B-SJ, Silva WJ, and Humphrey JR (1997) Strong ground motion attenuation
+relationships for subduction zone earthquakes. Seismological Research Letters 68(?): 58–73.
diff --git a/docs/Site-Specification.md b/docs/Site-Specification.md
new file mode 100644
index 000000000..04b002b88
--- /dev/null
+++ b/docs/Site-Specification.md
@@ -0,0 +1,111 @@
+# Site Specification
+
+(TODO update etc and/or javadoc links)
+
+The sites at which to perform hazard and related calculations may be defined in a variety of
+ways. Examples of the file formats described below are available in the resource directory:
+[`etc/nshm`](/usgs/nshmp-haz/tree/master/etc/nshm).
+
+__Note on Coordinates:__ *nshmp-haz* supports longitude and latitude values in the closed
+ranges `[-360° ‥ 360°]` and `[-90° ‥ 90°]`. Note, however, that mixing site and/or source
+coordinates across the antimeridian (the -180° to 180° transition) will yield unexpected results.
+For Pacific models and calculations, always use positive or negative longitudes exclusively.
+
+## Site String
+
+For the case of running a single site of interest, most *nshmp-haz* programs accept a
+comma-delimited string of the form: `name,lon,lat[,vs30,vsInf[,z1p0,z2p5]]`, where `vs30`, `vsInf`,
+`z1p0`, and `z2p5` are optional. Note that if `vs30` is supplied, so too must `vsInf`. Likewise if
+`z1p0` is supplied, so too must `z2p5`. If the string contains any spaces, escape them or wrap the
+entire string in double quotes.
+
+For any site parameter values that are not supplied on the command line or in the file formats
+below, the following defaults are used (see the `site` member of the
+[configuration](calculation-configuration) file):
+
+```text
+ name: Unnamed
+ vs30: 760.0
+ vsInf: true
+ z1p0: null (GMM will use default basin depth model)
+ z2p5: null (GMM will use default basin depth model)
+```
+
+For basin depth parameters `z1p0` and `z2p5`, a `null` value indicates that a GMM should use
+it's 'default' basin depth scale factor.
+
+## Comma-Delimited Format (\*.csv)
+
+* Header row must identify columns.
+* Valid and [optional] column names are:
+ `[name,] lon, lat [, vs30] [, vsInf] [, z1p0] [, z2p5]`
+* At a minimum, `lon` and `lat` must be defined.
+* Columns can be in any order and any missing fields will be populated with the default values
+ listed above.
+* If a site `name` is supplied, it is included in the first column of any output curve files.
+
+## GeoJSON Format (\*.geojson)
+
+Although more verbose than the comma-delimited format, [GeoJSON](http://geojson.org) is a more
+versatile format for encoding geographic data. *nshmp-haz* uses GeoJSON for both lists of sites
+and to define map regions. If you encounter problems when formatting JSON files, use
+[JSONLint](http://jsonlint.com) or [GeoJSONLint](http://geojsonlint.com) for validation.
+
+### Site Lists
+
+A site list is expected as a `FeatureCollection` of `Point` features. For example:
+
+```json
+{
+ "type": "FeatureCollection",
+ "features": [
+ {
+ "type": "Feature",
+ "geometry": {
+ "type": "Point",
+ "coordinates": [-122.25, 37.80]
+ },
+ "properties": {
+ "title": "Oakland CA",
+ "vs30": 760.0,
+ "vsInf": true,
+ "z1p0": 0.048,
+ "z2p5": 0.607
+ }
+ }
+ ]
+}
+```
+
+As with the CSV format, the minimum required data is a `geometry` `coordinates` array. All
+`properties` are optional. When using GeoJSON, the `title` property maps to the name of the site.
+Additional properties, if present, are ignored by *nshmp-haz* but permitted as they may be
+relevant for other applications. For example, [styling
+properties](https://help.github.com/articles/mapping-geojson-files-on-github/#styling-features)
+may be used to improve rendering in mapping applications. For a fully fledged example, see the
+[NSHM test sites](/usgs/nshmp-haz/blob/master/etc/nshm/sites-nshmp.geojson) file.
+
+### Map Regions
+
+GeoJSON is also used to define *nshmp-haz* map regions. For example, see the file that defines a
+region commonly used when creating hazard and other maps for the
+[Los Angeles basin](/usgs/nshmp-haz/blob/master/etc/nshm/map-la-basin.geojson).
+
+
+A map region is expected as a `Polygon` `FeatureCollection`. Currently, *nshmp-haz* only supports
+a `FeatureCollection` with 1 or 2 polygons. When a single polygon is defined, it must consist of a
+single, simple closed loop. Additional arrays that define holes in the polygon (per the GeoJSON
+spec) are not processed and results are undefined for self-intersecting coordinate arrays. This
+polygon feature supports the same (optional and/or extra) `properties` as the `Point` features
+described above. The site properties are applied to all sites in the defined region. In addition,
+this feature *must* define a `spacing` property with a value in decimal degrees that governs the
+site density within the region. This polygon defines the area over which hazard calculations are
+to be performed.
+
+A second polygon may be used to define a map region. This polygon *must* be defined first, *must*
+have a feature `id` of `Extents`, and *must* be rectangular (in a mercator projection) with edges
+parallel to lines of latitude and longitude. Any points in the 'calculation' polygon outside the
+'extents' polygon are ignored; hazard values at any points within the 'extents' polygon but
+outside the 'calculation' polygon are set to zero. For an example, see the
+[NSHMP Western US](/usgs/nshmp-haz/blob/master/etc/nshm/map-wus.geojson) map site file.
+(TODO This needs updating; link to conus-2018 active crust map-region.geojson).
diff --git a/docs/Source-Types.md b/docs/Source-Types.md
new file mode 100644
index 000000000..0b6dfa3ce
--- /dev/null
+++ b/docs/Source-Types.md
@@ -0,0 +1,629 @@
+# Source Types
+
+Earthquake source representations take a variety of forms in a NSHM. They may be well-defined
+finite fault surfaces or distributed grids of more general geometry with uniform or spatially
+varying rates, as are used to represent earthquakes of unknown location. Both classes of geometry
+are used in all tectonic settings. For instance, finite source geometries are used for crustal
+faults in active and stable continental regions, as well as to define the ruptures surfaces of
+possible subduction interface earthquakes. Distributed grids of sources are commonly used to
+represent models of smoothed seismicity in both crustal and subduction intraslab settings but
+may also be used for fault zones where there is a history of large earthquakes but the fault
+geometry itself is unknown or very poorly defined.
+
+[[_TOC_]]
+
+Example source
+configuration files are provided with each [source type](source-types) description. Configuration
+files must be fully specified with `null` JSON member values used to specify 'do nothing' where
+appropriate.
+
+Source models for use with *nshmp-haz* are defined using [JSON](https://www.json.org) and [GeoJSON](https://geojson.org). *nshmp-haz* makes determinations about how to represent a source based on a GeoJSON geometry type in conjunction with supporting JSON configuration files.
+
+Values in source model files in ALL_CAPS generally map to enum types, [for example](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/gmm/Gmm.html).
+
+__Note on Coordinates:__ *nshmp-haz* supports longitude and latitude values in the closed ranges `[-360°‥360°]` and `[-90°‥90°]`. Note, however, that mixing site and/or source coordinates across the antimeridian (the -180° to 180° transition) will yield unexpected results. For Pacific models and calculations, always use positive or negative longitudes exclusively.
+
+### Model Initialization Parameters
+
+Model initialization parameters *must* be supplied; there are no default values. In addition, these parameters may *not* be overridden once a model has been initialized in memory. However, one can configure parts of a model differently, [for example](/usgs/nshmp-model-cous-2014/blob/master/Western%20US/Interface/config.json).
+
+Parameter | Type | Notes |
+--------- | ---- | ----- |
+__`model`__ |
+ `.name` |`String` |
+ `.surfaceSpacing` |`Double` |(in km)
+ `.ruptureFloating` |`String` |[RuptureFloating](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/eq/fault/surface/RuptureFloating.html)
+ `.ruptureVariability` |`Boolean` |
+ `.pointSourceType` |`String` |[PointSourceType](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/eq/model/PointSourceType.html)
+ `.areaGridScaling` |`String` |[AreaSource.GridScaling](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/eq/model/AreaSource.GridScaling.html)
+
+
+### Outline
+
+* [Area Sources](#area-sources)
+* [Cluster Sources](#cluster-sources)
+* [Fault Sources](#fault-sources)
+* [Grid Sources](#grid-sources)
+* [Interface Sources](#interface-sources)
+* [Slab Sources](#slab-sources)
+* [System Sources](#system-sources)
+
+* Basic source types
+* Fault Modeling Approaches
+ * cluster models are a source model specialization; currently used in both cratonic and active crustal environments.
+ * system
+
+### Zone Sources
+
+Zone (or area) sources are similar to [Grid Sources](#grid-sources) except that a single MFD
+applies to an entire area with rates proportionally scaled to the relative area represented by
+each grid node.
+
+**zone-config.json:** Source model properties
+
+```json
+{
+ "grid-spacing": 0.1,
+ "point-source-type": "FIXED_STRIKE",
+ "rupture-scaling": "NSHM_POINT_WC94_LENGTH",
+ "max-depth": 22.0,
+ "focal-mech-tree": [
+ { "id": "STRIKE_SLIP", "weight": 1.0 }
+ ],
+ "grid-depth-map": {
+ "all": {
+ "mMin": 4.5,
+ "mMax": 9.5,
+ "depth-tree": [
+ { "id": "5 km", "weight": 1.0, "value": 5.0 }
+ ]
+ }
+ }
+}
+```
+
+### Cluster Sources
+
+Cluster sources are composed of two or more fault sources that rupture independently but very
+closely spaced in time. Ground motions from cluster sources are modeled as the joint probability
+of exceeding ground motions from each independent event.
+
+A source in a cluster may only have an mfd-tree composed of `Mfd.Type.SINGLE` MFDs and the
+mfd-trees must matching across all sources in a cluster (i.e. each mfd-tree has the same IDs
+and weights).
+
+```xml
+<!-- deprecated XML format -->
+<?xml version="1.0" encoding="UTF-8"?>
+<ClusterSourceSet name="Source Set Name" weight="1.0">
+
+ <!-- (optional) Settings block for any data that applies to all
+ sources. -->
+ <Settings>
+
+ <!-- (optional) The reference MFD to use. Note: Cluster sources
+ only support SINGLE MFDs at this time. -->
+ <DefaultMfds>
+ <IncrementalMfd type="SINGLE" weight="1.0" id="name"
+ rate="0.002" floats="false" m="0.0" />
+ </DefaultMfds>
+
+ <!-- Although not used, a rupture scaling model is required
+ to initalize the fault sources nested in each cluster. -->
+ <SourceProperties ruptureScaling="NSHM_FAULT_WC94_LENGTH" />
+
+ </Settings>
+
+ <!-- Sources must follow Settings ... -->
+ <Cluster name="Cluster Source Name" id="0" weight="0.2">
+ <Source name="Fault Source Name" id="0">
+
+ <!-- Specify MFDs; only SINGLE is supported -->
+ <IncrementalMfd type="SINGLE" weight="0.2" id="name" m="6.6" />
+ <IncrementalMfd type="SINGLE" weight="0.5" id="name" m="6.9" />
+ <IncrementalMfd type="SINGLE" weight="0.3" id="name" m="7.3" />
+
+ <!-- Then geometry ... -->
+ <Geometry dip="45.0" rake="0.0" width="14.0">
+
+ <!-- Trace must follow right-hand rule. -->
+ <!-- Individual locations specified by whitespace
+ separated tuples of longitude,latitude,depth
+ (NO SPACES); same as KML <coordintes/> format. -->
+ <Trace>
+ -117.0,34.0,0.0
+ -117.1,34.1,0.0
+ -117.3,34.2,0.0
+ ...
+ </Trace>
+ </Geometry>
+ </Source>
+ </Cluster>
+
+ <!-- Add more sources ... -->
+ <Cluster />
+ ...
+</ClusterSourceSet>
+```
+
+### Finite Fault Sources
+
+Fault source representation. This class wraps a model of a fault geometry and
+a list of magnitude frequency distributions that characterize how the fault
+might rupture (e.g. as one, single geometry-filling event, or as multiple
+smaller events) during earthquakes. Smaller events are modeled as 'floating'
+ruptures; they occur in multiple locations on the fault surface with
+appropriately scaled rates.
+
+Many fault-based earthquake sources are strightforward to model using a single geojson file that
+
+```json
+{
+ ...TODO
+}
+```
+
+MFDs associated with finite fault models may be explicitely defined or or derived from slip rates.
+
+```json
+"magScalingTree": [
+ { "id": "WC94_LENGTH", "weight": 1.0 }
+],
+"dipVariants": [
+ {
+ "dipTree": {
+ "type": "THREE_POINT",
+ "applyTo" : "NORMAL",
+ "label": "δ", --> label e.g. δ35 δ50 δ65
+ "offset": 15.0
+ }
+ }
+]
+```
+
+##### Geodetic slip variants
+
+```json
+"rateModels": [
+ {
+ "id": "BIRD",
+ "rake": -90.0,
+ "type": "SLIP",
+ "value": 0.03
+ },
+ {
+ "id": "GEO",
+ "rake": -90.0,
+ "type": "SLIP",
+ "value": 0.018
+ },
+ {
+ "id": "ZENG",
+ "rake": -90.0,
+ "type": "SLIP",
+ "value": 0.04
+ }
+]
+
+"rateModels": [
+ {
+ "id": "A_PRIORI",
+ "rake": -90.0,
+ "type": "PROBABILITY_OF_ACTIVITY",
+ "value": 0.04
+ }
+]
+```
+
+##### `fault-config.json`
+
+```json
+{
+ "surface-spacing": 1.0,
+ "rupture-scaling": "NSHM_FAULT_WC94_LENGTH",
+ "rupture-floating": "NSHM",
+ "normal-fault-dip-tree": [
+ { "id": "δ+15°", "weight": 0.2, "value": 15.0 },
+ { "id": "δ", "weight": 0.6, "value": 0.0 },
+ { "id": "δ-15°", "weight": 0.2, "value": -15.0 }
+ ]
+}
+```
+
+
+### Fault Zone (Area) Sources
+
+```json
+{
+ "type": "Feature",
+ "id": 720,
+ "geometry": {
+ "type": "Polygon",
+ "coordinates": [[
+ [-86.72464, 39.34245],
+ [-87.87724, 37.67532],
+ [-88.10853, 37.69013],
+ [-88.25009, 37.67544],
+ [-88.42465, 37.70361],
+ [-88.68714, 37.75289],
+ [-87.42964, 39.67601],
+ [-86.72464, 39.34245]
+ ]]
+ },
+ "properties": {
+ "name": "Fault Zone Name",
+ "state": ["IL", "IN"],
+ "rate": "wabash.csv",
+ "strike": 26.639674,
+ "mfd-tree": [
+ { "id": "M1", "weight": 0.05, "value": { "type": "SINGLE", "properties": { "m": 6.75, "rate": 0.001 }}},
+ { "id": "M2", "weight": 0.25, "value": { "type": "SINGLE", "properties": { "m": 7.00, "rate": 0.001 }}},
+ { "id": "M3", "weight": 0.35, "value": { "type": "SINGLE", "properties": { "m": 7.25, "rate": 0.001 }}},
+ { "id": "M4", "weight": 0.35, "value": { "type": "SINGLE", "properties": { "m": 7.50, "rate": 0.001 }}}
+ ]
+ }
+}
+```
+
+### Fault sources with complex logic trees
+
+It is not uncommon for rupture models to be defined by complex logic trees. In this instance, a `rupture
+
+```xml
+<!-- deprecated XML format -->
+<?xml version="1.0" encoding="UTF-8"?>
+<FaultSourceSet name="Source Set Name" weight="1.0">
+
+ <!-- (optional) Settings block for any data that applies to all
+ sources. -->
+ <Settings>
+
+ <!-- (optional) The reference MFDs to use. -->
+ <DefaultMfds>
+ <IncrementalMfd type="SINGLE" weight="0.6667" id="name"
+ rate="0.0" floats="false" m="0.0" />
+ <IncrementalMfd type="GR" weight="0.3333" id="name"
+ a="0.0" b="0.8" dMag="0.1" mMin="5.0" mMax="7.0" />
+ ...
+ </DefaultMfds>
+
+ <!-- (optional) A magnitude uncertainty model that will be
+ applied to every source:
+ - <Epistemic/> varies mMax and scales variant rates by
+ the supplied weights; it is only ever applied to SINGLE
+ and GR MFDs.
+ - 'cutoff' is magnitude below which uncertainty will be
+ disabled.
+ - <Aleatory/> applies a (possibly moment-balanced) ±2σ
+ Gaussian distribution to mMax; it is only ever applied
+ to SINGLE MFDs (possibly in conjunction with epistemic).
+ - 'count' is the number of magnitude bins spanned by
+ the distribution.
+ - <Aleatory/> or '<Epistemic/>', or the entire block
+ may be omitted. -->
+ <MagUncertainty>
+ <Epistemic cutoff="6.5"
+ deltas="[-0.2, 0.0, 0.2]" weights="[0.2, 0.6, 0.2]" />
+ <Aleatory cutoff="6.5"
+ moBalance="true" sigma="0.12" count="11" />
+ </MagUncertainty>
+
+ <SourceProperties ruptureScaling="NSHM_FAULT_WC94_LENGTH" />
+
+ </Settings>
+
+ <!-- Sources must follow Settings ... -->
+ <Source name="Fault Source Name" id="0">
+
+ <!-- Specify MFDs ...
+ - at a minimum, 'type' must be defined, assuming
+ reference MFDs are present. -->
+ <IncrementalMfd type="SINGLE" rate="1.0" m="7.4" />
+ <IncrementalMfd type="GR" a="1.0e-2" dMag="0.1" mMax="7.4" />
+
+ <!-- Then geometry ... -->
+ <Geometry depth="1.0" dip="45.0" rake="0.0" width="14.0">
+
+ <!-- Trace must follow right-hand rule. -->
+ <!-- Individual locations specified by whitespace separated
+ tuples of longitude,latitude,depth (NO SPACES); same
+ as KML <coordintes/> format. -->
+ <Trace>
+ -117.0,34.0,0.0
+ -117.1,34.1,0.0
+ -117.3,34.2,0.0
+ ...
+ </Trace>
+ </Geometry>
+ </Source>
+
+ <!-- Add more sources ... -->
+ <Source />
+ ...
+</FaultSourceSet>
+```
+
+### Grid Sources
+
+expectation that all MFDs are some flavor of GR*
+
+Always floats when used for a fault source; never floats for grid sources. 'a' is the incremental log10(number of M=0 events).
+
+grid polygons generally offset (expanded) due to includes() operations on grid nodes.
+
+grid sources must define a rate-tree, even if it is a singleton.
+
+ANy grid sources/rates defined outside grid polygon are skipped.
+
+No `mfd-config` for grid, slab, or zone sources at this time. (implies we don't use epi or aleatory variability in grid-based source MFDs)
+
+...tapered GR Currently only used for grid sources.
+
+```xml
+<!-- deprecated XML format -->
+<?xml version="1.0" encoding="UTF-8"?>
+<GridSourceSet name="Source Set Name" weight="1.0" id="0">
+
+ <!-- (optional) Settings block for any data that applies to all
+ sources. -->
+ <Settings>
+
+ <!-- (optional) The reference MFDs to use; although optional,
+ using reference MFDs greatly reduces grid source file
+ sizes. -->
+ <DefaultMfds>
+ <IncrementalMfd type="GR" weight="1.0" id="name"
+ a="0.0" b="0.8" dMag="0.1" mMax="7.0" mMin="5.0" />
+ <IncrementalMfd type="INCR" weight="1.0" id="name"
+ mags="[5.05, 5.25, 5.45, 5.65, 5.85, 6.05, 6.25, 6.45]"
+ rates="[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]" />
+ ...
+ </DefaultMfds>
+
+ <!-- Grid sources require attitional information about the
+ distribution of focal mechanisms and depths to use:
+ - 'magDepthMap' is a ';' separated list cutoff magnitudes
+ mapped to depths and associated weights. In the example
+ below events of M<6.5 are located at a depth of 5 km,
+ with a full weight of 1. The [depth:weight] mapping may
+ contain multiple, ',' separated values, e.g.
+ [6.5::[5.0:0.8,1.0:0.2], ...].
+ - 'maxDepth' constrains the maximum depth of any finite
+ point source representations.
+ - 'focalMechMap' is a ',' separated list of focal
+ mechanism identifiers and associated wieghts.
+ - In both maps above, weights must sum to 1.
+ - Use 'NaN' for unknown strike. Note that if a strike
+ value is defined, sources will be implementated as
+ FIXED_STRIKE and any configuration settings will be
+ ignored. -->
+ <SourceProperties
+ magDepthMap="[6.5::[5.0:1.0]; 10.0::[1.0:1.0]]"
+ maxDepth="14.0"
+ focalMechMap="[STRIKE_SLIP:0.5,NORMAL:0.0,REVERSE:0.5]"
+ ruptureScaling="NSHM_POINT_WC94_LENGTH"
+ strike="120.0" />
+ </Settings>
+
+ <!-- Nodes are specialized <IncrementalMfd/> elements that specify
+ the location of individual grid sources and have the necessary
+ attributes to define the MFD for the source. -->
+ <Nodes>
+ <Node type="GR" a="0.0823" mMax="7.2">-119.0,34.0,0.0</Node>
+ <Node type="GR" a="0.0823" mMax="7.1">-119.1,34.0,0.0</Node>
+ <Node type="GR" a="0.0823" mMax="6.8">-119.2,34.0,0.0</Node>
+ <Node type="GR" a="0.0823" mMax="7.1">-119.3,34.0,0.0</Node>
+ <Node type="SINGLE" rates="[1.0e-2, ...]">-119.4,34.0,0.0</Node>
+ <Node type="SINGLE" rates="[1.0e-2, ...]">-119.5,34.0,0.0</Node>
+ <Node type="GR" a="0.0823" mMax="6.9">-119.3,34.0,0.0</Node>
+ ...
+ </Nodes>
+</GridSourceSet>
+```
+
+##### `grid-config.json`
+
+```json
+{
+ "grid-spacing": 0.1,
+ "point-source-type": "FINITE",
+ "rupture-scaling": "NSHM_POINT_WC94_LENGTH",
+ "max-depth": 22.0,
+ "focal-mech-tree": [
+ { "id": "STRIKE_SLIP", "weight": 1.0 }
+ ],
+ "grid-depth-map": {
+ "small-magnitude": {
+ "mMin": 4.5,
+ "mMax": 6.5,
+ "depth-tree": [
+ { "id": "5 km", "weight": 1.0, "value": 5.0 }
+ ]
+ },
+ "large-magnitude": {
+ "mMin": 6.5,
+ "mMax": 9.5,
+ "depth-tree": [
+ { "id": "1 km", "weight": 1.0, "value": 1.0 }
+ ]
+ }
+ }
+}
+```
+
+A `grid-depth-map` defines a mapping of magnitude ranges to logic trees of depth distributions. The map can use arbitrary names as keys, but the magnitude ranges defined by each member must be non-overlapping. The magnitude ranges are interpreted as closed (inclusive) – open (exclusive), e.g. [mMin..mMax).
+
+## Grid Data Files (*.csv)
+
+TODO move to grid source type??
+
+Gridded data are stored in comma-delimited files that are usually sorted by increasing longitude
+then latitude (lower-left to upper-right). While most gridded rate files contain columns of
+longitude, latitude, and rate, some may contain depth values (intraslab sources), maximum
+magnitude caps, or other values.
+
+
+### Subduction Interface Sources
+
+```xml
+<!-- deprecated XML format -->
+<?xml version="1.0" encoding="UTF-8"?>
+<SubductionSourceSet name="Source Set Name" weight="1.0">
+
+ <!-- See Fault Sources for 'Settings' examples. -->
+ <Settings />
+
+ <!-- Sources must follow Settings ... -->
+ <Source name="Subduction Source Name" id="0">
+
+ <!-- Specify MFDs ... -->
+ <IncrementalMfd type="SINGLE" weight="1.0" id="name"
+ rate="1.0" m="8.2" />
+
+ <!-- Then geometry ... -->
+ <Geometry rake="90.0">
+
+ <!-- As with Fault Sources, trace must follow right-hand
+ rule. -->
+ <!-- Individual locations specified by whitespace separated
+ tuples of longitude,latitude,depth (NO SPACES); same as
+ KML <coordintes/> format. -->
+ <Trace>
+ -124.7,41.0,0.0
+ -124.6,44.0,0.0
+ -124.5,47.0,0.0
+ ...
+ </Trace>
+
+ <!-- (optional) Subduction sources may specify a lower trace,
+ also following the right-hand-rule. If a lower trace
+ is NOT defined, the parent geometry element must include
+ 'depth', 'dip', and 'width' attributes in the same manner
+ as a fault source. -->
+ <LowerTrace>
+ -124.5,41.0,0.0
+ -124.4,44.0,0.0
+ -124.3,47.0,0.0
+ ...
+ </LowerTrace>
+ </Geometry>
+ </Source>
+
+ <!-- Add more sources ... -->
+ <SubductionSource />
+ ...
+
+</SubductionSourceSet>
+```
+
+##### `interface-config.json`
+
+```json
+{
+ "surface-spacing": 5.0,
+ "rupture-scaling": "NSHM_SUB_GEOMAT_LENGTH",
+ "rupture-floating": "STRIKE_ONLY"
+}
+```
+
+### Subduction Intraslab Sources
+
+Subduction intraslab sources are currently specified the same way as [Grid Sources](#grid-sources).
+
+##### `slab-config.json`
+
+```json
+{
+ "grid-spacing": 0.1,
+ "point-source-type": "FINITE",
+ "rupture-scaling": "NSHM_SUB_GEOMAT_LENGTH",
+ "focal-mech-tree": [
+ { "id": "STRIKE_SLIP", "weight": 1.0 }
+ ]
+}
+```
+
+### System Sources
+
+Fault system source sets require three files:
+
+* `fault_sections.xml`
+* `fault_ruptures.xml`
+* `grid_sources.xml`
+
+that are placed together within a _source group_ folder. Fault system source sets represent a single logic-tree branch or an average over a group of branches and has a gridded (or smoothed seismicity) source component that is coupled with the fault-based rates in the model.
+
+`fault_sections.xml` defines the geometry of a fault network as a set of indexed fault sections:
+
+```xml
+<!-- deprecated XML format -->
+<?xml version="1.0" encoding="UTF-8"?>
+<SystemFaultSections name="Source Set Name">
+
+ <!-- Specify section 'index' and 'name' -->
+ <Section index="0" name="Section Name">
+
+ <!-- Specify section geometry -->
+ <Geometry aseis="0.1" dip="50.0" dipDir="89.459"
+ lowerDepth="13.0" upperDepth="0.0">
+
+ <!-- Unlike Fault Sources, trace does not need to follow
+ right-hand rule as 'dipDir' is supplied above. -->
+ <!-- Individual locations specified by whitespace separated
+ tuples of longitude,latitude,depth (NO SPACES); same as
+ KML <coordintes/> format. -->
+ <Trace>
+ -117.75,35.74,0.00
+ -117.76,35.81,0.00
+ </Trace>
+ </Geometry>
+ </Section>
+
+ <!-- Add more sections ... -->
+ <Section />
+</IndexedFaultSections>
+```
+
+`fault_ruptures.xml` defines the geometry of fault sources, referencing fault sections by index:
+
+```xml
+<!-- deprecated XML format -->
+<?xml version="1.0" encoding="UTF-8"?>
+<SystemSourceSet name="Source Set Name" weight="1.0">
+
+ <!-- <Settings/> block may be included; see Fault Sources and
+ Grid Sources for examples. -->
+
+ <!-- Sources must follow Settings ...
+ - indexed fault sources do not require a name.-->
+ <Source>
+
+ <!-- Specify MFDs ... -->
+ <IncrementalMfd rate="1.0e-05" floats="false" m="6.58" type="SINGLE"
+ weight="1.0" />
+
+ <!-- Then geometry ...
+ - 'indices' is an array of index ranges, ordered from
+ one end of the source to the other -->
+ <Geometry indices="[[0:5],[13:22],[104:106]" rake="0.0" />
+
+ </Source>
+
+ <!-- Add more sources ... -->
+ <Source />
+ ...
+
+</IndexedFaultSourceSet>
+```
+
+### Fault Section Stitching
+
+When multiple sections are defined for a rupture, the ruptures must be defined in an order that
+preserves the U.S. structural geology right-hand-rule. When stitched together, repeated locations
+at the enpoints of adjacent sections, if present, are removed. The properties of the first section
+govern the properties of the stitched fault, however, a rupture-set _may_ include a properties
+member, the contents of which will override the properties of the first stitched section. Although
+it would be better to have geometric properties of stitched sections be calculated dynamically,
+the current approach preserves support for past models. A rupture-set _may_ also include a
+`coordinates` member that can be used to represent a smoothed trace geometry where stitched
+sections do not share common endpoints.
diff --git a/docs/USGS-Models.md b/docs/USGS-Models.md
new file mode 100644
index 000000000..7db49c8f7
--- /dev/null
+++ b/docs/USGS-Models.md
@@ -0,0 +1,37 @@
+# USGS Models
+
+USGS National Seismic Hazard Models (NSHMs) are updated every so often to incorporate
+best-available science. For the conterminous U.S., updates historically occurred about every six
+years. This window is narrowing, however, and updates are also being undertaken to update the
+models for states and territories outside the conterminous U.S. These pages describe the models
+that are available and some of the history and versions of each. The models are intended for use
+with the USGS probabilistic earthquake hazard codebase:
+[*nshmp-haz*](https://github.com/usgs/nshmp-haz).
+
+As specified in this documentation, NSHM files are organized by tectonic setting and then further
+by source type. For larger models, such as that of the conterminous U.S., sources are commonly
+grouped in folders by state. Documentation of each model is usually published as one or more
+journal articles or a USGS Open-File report with accompanying data releases of model ingrediants
+and hazard curves and maps. See the
+[USGS Seismic Hazard Maps](https://www.usgs.gov/natural-hazards/earthquake-hazards/seismic-hazard-maps-and-site-specific-data)
+page for links to all published models.
+
+Each model region has a dedicated repository with version tags marking different model editions:
+
+* [Conterminous U.S.](/ghsc/nshmp/nshm-conus)
+* [Hawaii](/ghsc/nshmp/nshm-hawaii)
+* Alaska - _update not yet published_
+* Guam & Marianas - _update not yet published_
+* Puerto Rico & U.S. Virgin Islands - _update not yet published_
+* Samoa & Pacific Islands - _update not yet published_
+
+## Related Pages
+
+* [Model Editions](model-editions)
+* [Logic Trees & Uncertainty](logic-trees-&-uncertainty)
+
+[**Documentation Index**](readme)
+
+---
+ [U.S. Geological Survey](https://www.usgs.gov)
+National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md
new file mode 100644
index 000000000..a5db3cb4c
--- /dev/null
+++ b/docs/_Sidebar.md
@@ -0,0 +1,18 @@
+[Home](home)
+[Building & Running](building-&-running)
+ – [Configuration](calculation-configuration)
+ – [Site Specification](site-specification)
+[Source Model Files](model-files)
+ – [Source Types](source-types)
+ – [Ground Motion Models](ground-motion-models)
+ – [USGS Models](usgs-models)
+ – [Uncertainties](uncertainties-in-nshms)
+[Examples](https://github.com/usgs/nshmp-haz/tree/master/etc/examples)
+[Dependencies](developer-tools) and [Development](developer-basics)
+[Functional PSHA](functional-psha)
+[API Docs](http://usgs.github.io/nshmp-haz/javadoc)
+[License](https://github.com/usgs/nshmp-haz/blob/master/LICENSE.md)
+
+[<img valign="middle" src="images/usgs-icon.png">](https://www.usgs.gov) [U.S. Geological Survey](https://www.usgs.gov)
+
+National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/images/psha-formula.png b/docs/images/psha-formula.png
new file mode 100644
index 0000000000000000000000000000000000000000..7198c0b58ebb4ea311e34dd0de67bf97338d65cc
GIT binary patch
literal 38574
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%0Dm5<6cZp-8=?Y<8AGx_B~w+H-aUPU
z9&j^<t!4!lxEgu}@k(xqWW{*elSDL@_HkCX?78qtg%kAUZ?#C*a1!s0)M%(d!qxp{
zl?e-bF>`WJVH-JH3n{q{tHnPe5-pYbF#Bj)W(`wGxU;#YFx5R3n-J-5T1*7-sfR}r
zVU!Fzq!$@ejaAu}=Zhjv`k0xx6s?XGN!u$KmDe8&A;ho5WWfe_UXTU?(4~rABZt?m
zs{?H2n&e-=$B|ZA6Q^?PUdpTuW8{$KBKmUJ!VpaAQ1`NdPEoyp<-!l;4O`{o<a{Pb
z$ys>TI+R5YjIZVI?qvfvP9%Z@=$;{@GksEv_rxo_phER0K<WdU%MtIAfgUrCv*LN@
zt2(+(gi~XWBKqgSD`mmsZEuLA_73yByJ(;VUFI2ykPT$=n&y`hNG|eH!L=$LB78V}
zCDP2s#g!kJ;FN)wDfJ50z<l?7A^mAj^wlvm2u(Kl(z*0&wYhDF;7)MjGn4QRpBj&+
zSX9%N_BfDDad5JJ{y|LDTjwG3u@7&t;4+trB8nMb1rF07D;|lGJkwR(vb2V3_U^D_
z)}Zz@`5Y~|*g(rB5Y6JOGL=WZuz7#|$0*N1b)_RVF`e<U7Srue@Z@E~&iyfHHH=4u
zW1a%bfBO{1uPvOe*^+qdiZmBFQ?z|A-`+Q2+JKvIq)?4P%%f`$n{Tw*`@ze{E}lQH
zKbJ6`<`GV^N28@Y`%B6Vt&g!s!P^O=nX@(_18gVyPDOZMYu#WO*^ZZ?<m8oF)k}lx
zq_rso#v931iB7o0mu9iYI23jFx%tiWnQS{<<fW?Q!Jg^+&sW(Lu4h?G*jr4|jQ8Ra
zncvJ8?P3-<Yu9h)OQd~#0%40%atg`J*x55qCFZ9^ux72+b*}eD8zr{R#aJ(b>oD`8
zZ`I$`AI<n_4}o7$POIhh4-#TEYiJoFS!3IPq|Dv+cMa<n(;e;nZ1o3N@r^yPOln?p
z+)|_8vXV^hINMKRDqgGQ``<(Fd0RGQ+1mbMv-A4q$;GN_2D04^I|kB^q<OJRIP>;y
ziTRCT0J%ME0kMmy`5}1s`%JyFbVX>8cwn9pwexM?A?t9On8SKnwUVXZfb>SF)A<L=
z<ocyVN}CpDYPg09QNx!5?ZP>5^RApe-z_b>+X(HByQhBXGei~cg}b8H70k_AURc~1
z3EFBj?8Vyxhu>{JRtvRua8+_vDP(u7I!)K&f%8kqrOW14FT|zL)es7Veo-98<R+iC
znT=UQc}yef@({_4SY)8>tQ}Q(m{gs;E@361mp-L{%v?-m>B+j=uqAvKt~Ih!ABLl6
zUFqV>DAEI2ZS<D}ojTe%?9V*d9Ll!*q&)5le;^J*)@#fDsum$6BI5s53Z~Uh$Pmf~
zYFZ0fgMh&iT{nEv^KJT>`WrMS1w9NHkyrRWG<kty$V7x<^1kTn-}rvn2U(O$i$By;
zNDw%Xrb-M;U!1z6y-=K7RMI)iPb%3d+1c%;g{WF|H{8;__q=wLN*<Y;du+tCiQ$Z0
z>c5MAag7cE!f0>%73+-M!ufj72;CBRzouLsoeWSI7JMR{1Q&fsg328&lqRPLK{ygu
z8q5u-@9<5HtQNMN%XQoFV4ohR)=evK<N@#eiN*{Fy&bM<LRiQ<RvqHfp+2wrm0K)D
zmCJB0@4MceE`u{I6zFv8^uxJ1TUE+_>R!t1h2n;{1=eMCuG*a{kRDXw##iq2nO~Hv
zr6mn7RyMk4q!;7Kel2cXv;qIREmrlj#NSzC`!*o>d!a80R0D$(uh~SyRJ4qgH78~u
zY#KF}sh*Nank{_Sge>oMeaX>(v{{acA;NJO9_KpPKe^Sdem)9#A4;2Ymwm~JGWCAL
z?IQqkE*l(mVfvlN_GRcCZ)R-JhJdd+?@tMKy`U>~<DW^5x3g2hnDZ?5TVYC{Tm)6q
zyy1pLUT|aG&9SFz;1n|%MyvCJh$Oa0^X`uhl@^_OQ#%Bzg(P(+Px7S+a3KeT9w4E<
z00S=drW8|x2AoL~PfO6f$z0sJ$LaQu+|g<)Ei&ZN6XUZE62YZG%pYHVC3ziXvUZf}
z86?tvG3#(Y`q0){SbA%A6Ku!ph@>C-_6(CQ2dSWSs~BB{t6L?Mirn1qELt#UOL4Ho
z)m-3AuhRQQ;Yw*a0u|xR6LXPEW>&dd-vUwrbWgY^^8h_Us3NUi+SEXIF<kbi_HXXV
zBfML4%=itv#4Eq<dy(!Wdl&|WQ?L$AzPi`EDKPKc*hSd(ai8+q7`@%~&O*5yb$^lI
zZ0YKjnu?^aK<{<hESA{FYDk@3@G|M)pp17-c!D6lDE#*%wIyd{pb`u$T7S$mi%cZ8
z#XRC*1?Qb&mRYmV3&QrC*7sZ!$mf#YvII&(BB~{_JQT@WoV#|}^y$w%z`=^DsyWOS
zQv=63CO790=j9S>lL~H@)Os_IQ$ap0q{N<N_xfeW_A4zbxY>r$?f~f><E;wC$y&h!
z=;@~L3Fb40Nv%O|13Sj%Wt7)=mwWdK<)*)+H*#>tU5Zzjr-@uDwNQe1ju#xJd>gc^
z>&PVaS;KV@I58{|Lmau6$_&I}ZpGC1{S8cumMKWkrscltUxkq0f6jj0&4?4bvoY+f
za%Aoux=^>KT-oge12QVyim~{qBe%h%rQ%ur&~@w<n&cXFt<07tM`0I1XMQ$e-nm4#
z7XzT=Wi=FPWoI2I+f-8CDc)S~f#@hKK@G=}uMR&tL0~0gK;(<r+_$PtW}NwRxlti5
zF|oMvti?3Sh)77WEPJd|nW3;TIygvY)pcw9l}j1U+3r_Hd#CAFS65Y1KE+Cs8I_gF
zI}3Fc8(2B7+VI&|Rz8zck;Toljqr(_zrOQ#%c_qjZf2UwUV`}P)0Lqf-ee!&Ou8(i
zQ}aP8y`>RS!+GYIoP~1l!Y;L&jw9+<%`Z1RimYguhey-2l5M=YiaDz$ZZl`H8%NT|
zyJrgZQua9}oeF^ti=|`Ftx&e5Jd3CXz5<_`8yU8g=1F5<@GKp6BE>hC#}W54U28n2
z`-hi=mf)U|t)#tqa!TZDPa;<+HM~5=2R!C_`Zun5O@y0Nvz49z^rYsRt=7`2fFN9G
zUhH;QMO(EMzfV>$+=x}X;T~9&+npBcpN*}UhuE!Ac5M!%3fqphl@?ujAy)#d6mz|K
z3SAT7-S{3w<sKK-6j5ZaU~th#=CZHU8Z_%SHf(&k4r<%&8C@q7#HhYwcHfi`dM8tW
zPxEK^iXY}DMe9|($!=wPm}*h12JTbP)y=$?bSHfCBJ{Xfz2#@osBnmsdW2J)$4;Bn
z=i|tR&67X7d_SwRZPkeh;9irxoAfA(Uv3x!RFv>ejYS}(pw-THGKIq-q)DielE-r9
z{R<@uDwq^>+Z#fyVksO>siAhg8Chb-Ig@;$2Q!ac7Ry?*g0uSV9t1h+H;e8;8(1V4
zLxsOMs#*3)`*xSTZe)4~1|}{hfi~mptd2y2b<x@EweL!IuDE*_65T%}M%;Wkar@2t
zq^Unw7xryeSs;HlE;Og-@QxnM1)qJsrgTysy#Se{d#cLvoK0l3-{0Mc+!=-8a@coV
z&_Amc<4=tfD5*c-R5+AJG?uggJ*rF(>TF$<TrSNLD&hU7FQ*5K^W`CdHL!{xZ|b<J
z@5`*z*>>K&gC!;%2yR;Z9F+aMcU_c12Zvcw4kQHu&|HQRY51sh9;GRU!K$z>#R&|B
z{e}9(Lhdz8#Gig(&8wQGO|mAAQwt_9RB3L;B{;h)yx~|vtHL>b^brOiQM>Z3^$u0P
z7jNSB_bqwyuTHkUy9-E#qw+uVy+pXZKC#y@1#>eNh~ao}Ar(bqipf=3-t;YZOIq|t
z35!V@Z77brj27wI54W!wuEr#0^7gg6HlCND#l2I=6`U)R!c!iP#`&QCmDzNJKiq>T
zVy=4)t69$d$7;{dj?c6epW+eIAqD#Gd+%V<XA9h=hL$@n@~wH(jU!~N`~ieD3WQXn
zQHpYgd@_J1n3JJ8CO)}jpES3sTn*+6MBXACIM{TP7qZCJ^q8EZWAH}I8zzd3BoWg@
zTn6d!xdFsHwEcmudW0L-6i&7qQYR~YfxKhni#KP&2-L8_)BSCqqq|ygIi}Di{j{e0
zq#i~M7#S(XHmVgh80Sxgz8KI)^ForbY!F{{&Q%MZ;AYDlXdcxWwH%gIaEV(bmz+0_
zA>DC!N}H|)<91V(OEtvh<mUFvuq|d$JOE3#?*+l<jBW%%AO2gIYFaHziQ5z<EsfPk
zl1|2pFq(BU18#|fv_{?gk+M(ggQ!)?cTMu|+bb*Xx5Sf~>C(uae@h$!1)KDwwCPFX
zaH1;bf~!cG-A_%W7LX!ic=5ZhJ;#vH#qi0h4H9{3l`k#TVkeZQ2`>j!RkZBy$!q1D
zZmyX9EMo^tg#un5&zhv~JhuW^5~6>#2Yh#i?nd%8L@<TOrM?!+kxR!P_`;c*Z|c{g
z>9MgP2L+*@w<xI-Z7x($GF@t@8%W_$n%E(}3yNCJmd(F6+k(3y|EN3@k%mV$9*A;W
z%fBO6xWS`z7q&abyUIUtpt2ds9_cV-`d0Ti%3Je=;mymq@rpLK@%WCJM=jRL#Pwbq
zrSH~9xpRzBbPvIbuF>i44DT3(a2C>kRdV7y(sJ2Kb&(Vm{nq41rIfS%2^yXdnZZ|I
z<G!<7bX8+oYODGz)HP;g*t=PU-qWeE>Aa*adHsq;ZhTDwY5!K2m+5XKcNmsK@oao@
zs*$1G(4uVtTB@NW65t5w5hL)-qHtJp+mg6ASUjtZho<u24m-NZir*b-b_<258+X&h
z^3JPloDHzR^H!*+#HBPN>?<|e@(!YFC^7BNRTZM4q4gx1q+x4cFL@kFYz?JujLXSj
zs!GqJ3KOP5r++>UTHoC41A1%;7DA`!<LR`>b-<26Th>4r4h_J3^YVsu#vKyl;xKT(
z^4wppof*L>$`Ptu=Z@Va)44o9JD5-e714b^UjJU4Q;2{44qEr^40zQ-O10i8gc(_d
z+#>F?v1P7q(cT#KSSQ%$R?9<QVq<UNJJ+5|C!Qvoo-z7<i6;6j&SPZY@K7R}%<L>r
ztmS>1`<6wH%FQ%&y-|%YhhP_HUgcZE1mH=(s_1pVvWpl7-L#>~vJ<g;x=)53pPcw@
zS*zIH6Z`Pv!br0APoK!_oO7zp%_l7WzO)viUdp<Ezj2jaZ#dRTk%%IpYkLT`p<5QY
zIWsje%&~gow%#0)*KpeOS<krRxfYVqne})>Viy3=d+c<_ms;J>5LY~Va;jRdd_tpW
zkk`rvWOI~uDy-;1m?Z+g6IrI!SKEVjm3SO@Q&YNE>pVbnekO;_4_+d7*;)7ea}L8i
zYHk4U#$u|SeLM=ZCfE2}vb*cc`|-J7wRUUV7yRonc`xJ91ydQ76%JL$=f6#f0u&;=
z@f%V59ZD^GcjI$va9VSRdpP}Hv~ia4)XExk!;XIq1sfeXl0sbJV<_FGRZg{9?`ihj
zjm#vz-o@CcP9Uj^a$#K-lryv$`x2O7&F6K4bwSqf)=s8_FSAb+&=0-cbjt3BX697I
z)57bdd-<{`%wYQ1XuNkU`%YrVV|}X6_4ug6*H!7gw^0pl`XZ*U9j+5fsY7a?<p$Cs
zXywU{=TCt2^!RvRV!bE)bYm<AKZEWHP|=;S7MulXE);@B?k_8Ikt{Kdynm@lwhk%I
z&r|5P-y(R1fH}bF<-dKLKyhd0i=ldzY_$R_xo={i&L(*E?n>VCeLF1Rayd{A<JiRV
zTn0KJs}5%T%9OeByU#tx{9?D-X{R^TRq@oQy{d)!_ckAQH6aU{GCQes>;T?Li>>h}
zbuSypqxa~`Q}`J(FfgzZ{{u+*-3p(rPeng!U$(1~;n!}37Fsdhv0z4Cp7^8I<pwHQ
z?WZ(MsDS=Uxb6UGT}V3X5U!b7yGgjG<kjBd7IwdNLZ;=LFx|^i#YWxrc0THwX|`9w
zBG}wY&bLAYq~l=*qx4h$Y4B1H9x<5dSXPy><OVU>IY<T{s)|dwo3ZR#<fxW^aGT&8
zD#;P1x!y}`^u7GqAh&slSSY}71|&tFCNb@xWZ!C_G|4wckFaCpb-z8+=tLNP&Ly0|
z>8t$CaQ^xrHEwwRQsmd2juS?SrdpGjTXp)Vi_}GTj1>_!t;SJ#cEeo8+*b<x_i_2l
ze8+Dl?q7VG)^SNq69o`8F#y8Te}6W4RGACE`_ywRS!JtUyL(SPt{@#E{;DJN(I1Nz
z<ipTO@u%-*pP0#{3b5i>9j>(c1z$_k9vD`9>Lho<91-2EI?t)%(uFsL-ficJ74U=G
zp)j8F-zh4hh5KlR-@5iS_c}Md$c4hps%}@$FThv~e<dT0hX@%yf8Ny3L<FfAv-_uR
z5fa`rrYiKE^Ne!F)3Az&JGCkrh)rcRdeYW-x-M=fXU0JDq-o)1<>Xccl@b!k#q^Wg
z%~ba2(N7WNkHVVt`WO=({qurgE<EBK^4(F+5{0R^#FH+9)6WuW<D@KiC!M8u*n{F*
zeXaI5*15Na9h>HcOK=FEm!h2sn8R;ZM5zCbh57aUCoh|r(sQ9_CoTa1gBEFD+>%y`
zJ+SjP$+?53ZWGonar+goDs*&c>?T?4c`GJWR6b9WWyqcNT{)rydzK2yt;jPd7;Wm`
z6H0O#vICXTl>n(s9dnH#lJ71IbYIQz!_r*ZWc`;k-O?s7TiMWa=pW6uUd+w<?%5+n
zHc95-WQ9ici-WlBX1L{(Nr$QGOzVeks_&UEyQZ3~W(OTgUwSlEE#>Fp2fSEh64AhJ
z2h9q}MB(Lzm#IBxpLLL&Pz4wul-{vf7ZH$D=1)UIS^LYz@ZIF=5*oqHPH@%Hjgzs}
zi)kGG3fEZ4b)j_`4^P5#>q=-(e)v?UrNear2L29>LX)@hGR72055#OXCd{X*W7`T#
z<x(VByk-Y!mQ!7ZR^LPPWykHm{XOd}vN)N5z+1tB(rM;rc$#lV9Sr<UB{Qmgy?3re
zKF^@xYvnUCGWf4gcSv^qNqAg#nKO^)EI>PU(D1G@E7OfyM#DcC^W$g5H7hOY6Lo2x
zUCAW0M6NcLXK%}w7Blx-(}#`~E<1gmSIxIvtW<*DNgONEsAldjAYz&{nMAkPG1ymm
zE_<GW(m44A7HJ*m%11ww4PGe$fp@9h_KItSJ=5$mE86anOX1fyHhKZ#k~5>-jO3R%
ztkU5g<fSJDJ7dOyMf9M7BdZhA-^cPtUWX<>;rfD&_NFp}d7DL~%%)npJOo)4a#f?f
z?yh^Qt>(X201>h>z#SQc>#<)(q~*?+WZu1Y>6L!!<>^rZ^O~Ul_H_1KQs*Sm$xVi1
zBp2N9wRQhP&!)d7aX7#iB<1UUx2HFjErmJT;8vk~&osm?6vv=Pzsq!UY6OGK4_FU!
zUhy-}5S|Y}CPijZ2w>5JSZh^TMsjpUR1eSN_xJY=je_oo3G*3ys&@tz#_qxS?x9O%
zALAQbM~~c7_#J&gP1lkDFqX*Ud>_Gj0$?}Ms5Fht8=n{Tj_#he<vw?X&9OaC<&L{L
zsz_~<@yjGy$!k#v%MsOwCj{m!3}L~2uQ(2>8Yskl=cM@X+%gOy8X1UWR`j5*u{@l@
zqj_=-t(=ZJF{Qk`no?}r5L#(XG0V7|_bCB3!&m^IM@pl$j|p{%1T)neGurhmnHige
zEj=ClTv%3R21qP6fWG{fORcIbEvx`+<O<;XQgZi^IazbvSEeDx6NAO&jJvw3fS7tl
zU_n#Swh(F|s?m!G0c4hl4FH!~rVO2dmrN3~1i(CJs4I*G=nIJWHIYWTXGq$6)0E0<
z0P@TLGz^SjR>C9z0_1UV5UcQ0w6~Wcoi^Y#o}}~n3?K9oDm<FR(w$n*IGN~FKr^o{
zxa+-9W~AV5KqXh5W{ovnG=*H;@v*&=`Hpcb)qT~*uEVS%0Y4p4w}GB=g$v@&NLk2m
zwM#)t3UP!q6x?i7{&3S<Kn!?jzT4k^A$VL<<)X=mX27v!oRRRKlUip~2vFbk0lg~1
zg=|(nbTl+lj7&_~fRNU`#8><+lhE_WUHw<_4*~~x4vmgxBZA-LG;P)|mM+$-Xylkz
zzY-&+xUL2%Dk>7sEmNd_W@IM`I;XX=`n@d25Z3KgV0978g5S-^JAY7UV*k|#2iBE5
z8OOq(o5;t<2DTElqGE`X#x*hz@dv=ESZ+Q^J$(;t4-{3#0HF%@;TY`An#s5PfwfDx
zLjO47XTH%q6l^vsnwr!A0P`(`L%ac5ys`x#6#Fv%ToqEI2GYHb$x-QFIIB@M)=Q&m
z=Y2Um**Jb|v>NJ3%JdmsiWt5~qe9f)!GWac=#V(9`@Z<5Bc9vqQNkdQ%z2>CG|X6I
z+^6I3z&o?bTL5-EE9{Sj0NcVq5=(#8b4yK~&kuJOanz$ZqQCx<i}%S8zdXq`nIZ5T
zZe~GSfGUj*g6#{?lAg#@jc<f}U^0?izEdpN<lL)`8@pZ)8>6c6tNa+;qd7_P-13(;
zZg{(lItqjDC0_rfWq09_IHvE!+m8`+PP<W2gg!pqut21py3%mBsV|+vuHb&YZ>GBr
zE_IGiz3L=P*6@4(sGrwQ`tbqes1|(YtBfMgApHicdKWKglt~NxHy>1((S4zVWQdOk
z3@`^CyI)d(Cx^p&-Cvnt^SD=vtN{J!F#u_zR$Sc&MS1y;y%>I$7_W(eWyn7UyAAj@
zD8RSPAU>J+e}A+fe~cI`CHx9#i&TUV8NO#yO^>d#v-A31tJ0K+$#}r_&aWI@Bog3m
z6dkU?04{D5fC26nFL?ASUVv9ALkEO^^v?hK@KNy*U@d&{0a!_dzn}q*m<(FIChcV#
zP0gf7Qp(I%m34Pj01wtI(8fiU{IXnwJ@D~P3G|HcvTnc~JdXaq#e4i#iuk_A_>Az|
zqln5M0ZQNF0j6Q~a}MhTc5Hy##3)gV#LdkuuE@yHP#l;ry8fr<!IO&l@OGtf{SRX%
z)FzZk-IYSn8$fwl?ygAtOO0B9Nf`kQr`ILG>`(y(uc)-N5(Wp0jI1o-xhe|^5fKr0
zjEag1qv13j_mrpM^4r4zYOPx{91be}Ygs-y+{X`MBwGqCL(Dj0U}Sdalne~<7NEu{
z#+E6dq>{*D5k~<x!;A|F<2rekTpf~6%mS+msE^<Nahk6Fr{`rNz3;(T{KoQl)dCE@
z_pRO4>URd(9iRhyua&Ev7D)$dG_94@e1bBO+s$760Lu`G<P#JyClR)fR<#c7=K3^`
zgZ;N=eYc^dF|q&kOl=qp23^{%bnhn9<_wU#k&#g^K%iTYS#pa54<nqcYS9^tZol3W
z8R&+~>6kZ=%*L?FiSal%_zt~CHGlXY)STfCb-{O<dwpAh0lf8h48Vr?Vm-;Cr0iv>
z87w6|eOyBWw_GflqH$d`T@+&fqvP#>2OO_MS8p1s*3*XnZ@ZeHZE=ib!6}0U#<Y^q
z(i2Hy1bCUS?5*mrScVQ-p%DbYE206LY@GXlxt&mJP}I^FkeHqLH=w&dpk9V6(O(?&
zzGrhPiAWDn)h_ho@c|Zvhpgq3XZW{Kf0P4k`d`1EkoXADKHD#QUQANGVrWPdU}cy<
zaT5ksEGl5ZYCr!6RYToCzbv1v(U*E$6UM$kzjrTCelYNAR$J;JOja`w{tP6T)Cj=X
z3uXSN73B$R3j11RWRGi%{}u48$!8trPo|sjXfdO|{?h^}V8+nSHiQMU9!LCdHU7sp
zA3d1b=s^Y+84h5_`L}WW$2VM5VCjF5MEPTF{&COm@6Y@!z4Fcag8tXHt|ah-4X7d?
z!vG(CJea<$B4y8dXJvY&2j-RE+ApM+f*)^3mdPlRrUv6wRYbx?$-1D*1aJH~k_pO|
zR7)0=vPVlt_V!&p)Qt%lc-h+{|B&w;&~!9>c^Jd<G~`Pu{#oL1*4_x|Vo+~SOi0|D
z-r;+cJj&whLVzbupNiL2{`J8k4M2|+RjlRGOJubWiTS7AssLA6jG=D%C|rls$Gzi9
z5(T$s&(LfngawrS<Fe|Vda65u{?f3#iLVY{-vWvf^;Rl*cVcD}JREBu-YX_Driw^r
z^C{^hBNM4Y)#5Cjde!5BKE2NZ{6v4~Kjl&398!vp3fD)YjBAtQWnJ=c<l{JuAs1Z`
z`Ei^nc-8DdA6Z$+?6wkZMc;?5A@DeXc@it}XRzhqg_(j25stB*KrlJlbdzYK7UXnZ
zv>%;=s8i);NtXg#armm&Or5zz_mhXgqx$}B>^?pkKDqA`Sl~&3-}NHH??=8$PjpVX
z;o6y*Kywi)HO&2dyPIy*Gc$d*Kq+SORF?v-Jiwee8Ml`r4{)|I38LVM3Tz^;Xk55o
zD75z&{U~8!SEsO^(qwP!K(ZSoPu#!_B|!d<5&NzqyzhzQ_Bam#)T<0{SQ*a;p^1Fq
z818765fF_>8AoQrOH;G_+oXT-jb_O^wq8l+O(6Dqv>-Yd*_(D;s=8j+-|FtqYff1u
zwk^tKqmsig5}j+I->==`+kd8`jjlICX^7JLcpml-+pJXumiDyjD{LSp<U=sU<Xm*(
zr;kqOO(%MDYn|1A8K{kFrmvkB+5ju{B<})Q#(m&V-(>gX^)nVDE!Axxq`+GoDQxV&
z{v}RF;iemD-_H0?PYZR_Qb$_#xW#5=@h9Gv*NA%|!H~);l9SCXFMCC|V|Pnh=T=Mb
zu+xZ087;Kv9#6Bt-3Go$i&CnVi4U^5|42*vcr)ROyYB-ULCjqz847%ixP}Bj#KlYL
zCi!LW5QLP1^hmVY@PegY&C4LaUN==Man;D)_OLaOk1T(=vW{7@joqlcQJNj*A4-RU
zk%pFF7h#5^5<Wg(4WNIP8doZL!{8bHq1@|mdA*VpKXtr3EYfq2x_ruf0O@$tphj|Q
z^GsxlMd`(?HNr5H)YGP-O)XFB&DWf`P)*J4alybvDR*Xy(nKsE6*WH{)AvS?;e%ws
zd83YI{+;$lq2(gZ*nWtDio)J9pBHhT-V4omGQv1*5DZ#`&fo3u88kk+_^Oe1cyOc@
zpwSj6sO-@lM$fT_z7P+BSbs5TgnO@y${=S$dYV|j-9`AJhB2~2Gu3sjO-2X9)!Tgg
z*3r9-E?%qC#aNj8p8-Gx8qlJv0HM;*&55$xCCQoW`g9W`<7Y>{9Z!9h;Yn#>@92Rh
z(JSv`Nb=sRaG(I~F|Ok&R<%tJdKm7s??*iev7#0-xvjY-tQk=&@bHg|Xa8g6&?7?>
zOPZkma-UnUW99X|uUwp>Y1|FPRY5P#@LulBDlncUu*icq(aomrbobiS4R&FtZaveb
z(kZ9awa)4_tV39=mI9vU8^za=V=XFqqioqJ+G*TA)WnkYfGRa<`g>Bh@EM!Lo`v%r
zrGref#*U{#7&D_8?j)_4XlNb1WrWrKe%0|pES`*(DvZ(+O;HCxjQ$Uoo`(YXGRZH^
zkIM%I=C$>l>8!;=2_2oCgK+QroN`8naH<sRrW7nC#0G@N8(V0gcPnOSL51Mnqd3?p
z@q!Ds<|2lO$qmuO$Mr5;DKGIOgv;P-ne^SKzUBBP5;iA}A$4QKY;b&j-k&xn2m^#C
zP(+V@lvMHKbl9t|gRna3A@li>zyN>h&GNq9UIZ<rWLPuFA4RiEf{f-T<kgRb5ai!Q
zEs=B<A@ws8iZ3B<niKUoG>D0FcZ1*1kwU@BFGhyUP25>^MiuLR$}qU)n}1t}3h(W6
zA&8@w39b1Wpg2#{&_Mg-B>%0AzbhgWHpZ`fcibkV@qC9NS1hqfVV;u7B#W|7+`vQd
zFAq6`JX1b3F`YMmaX3*u=aTK{jXHOsYg^~|`gKNZZ`W1yMojC)Hfwxisd&!v>@;I+
zR?`@oxEX^I2f|ad^l$V2iiC^a6iD{;SOnk?D=;9Pgz}`i>0)wB1^#Q7ZGrM-yfX7Q
zi;!uw0DIi*9wa$`jJKA}yfl$org`BN**3f!lkC700#)tKaa?0mzy2KOxurEdwHx5d
z{_cSSo1eLqcP=M9ZG~@PC98|dWtW|XB;M8-5dCGpACM@y4A0_o@`Hx=>2j4FrX2@v
zj(TvUs%a}u8_QSa#%z38PW+ax#Jf)O4)UF*AVGhGXP0U|T(h@Y7csa{Fj2In5Up`5
z%U#fBeOg@VI&PWAqcpxTs5A8nym}VYlOl`R{#3g)D+h-~o`=98WS>xtuKp+WQp3;~
zjX2~#W{97#91vf``4bf&E3yf2{!xEvWk3*mBW3N(LxNAFtjMks){95R!NKu%YECaE
z2dys&Vqmya-P}9N+mzhegr)VU`X%(sv#pKt-+_@23OsXIk(56sAU2N&cS_62lTrt6
zt|^YvG;z@v%u$gJ)B?I5YKQ~`)H*oAP>32SU|k|uvZt8j(S!UohsfkWEddJw>2YK*
z@G#Cj@oqVHA=@NY=G?^baLe-Q>Za}nA*}}I;)Go_$E;8DaR_gzQ9Tni>mX}o6a>&&
zn|l8|Z-ix%COhyBtCSdD)nNQMBOb}2M5Br^9KqqwAU=&RBaNemDXjq74Ibe9`<w!A
z&3HC0GKT#4ena^E1;XV7(YkM^`;>_+>m+o))8AF+b?%l6Rm~*GJh}V^DtX%e=F6EL
z_o=h7Ix9~Se6pDGyTPHu4JIYExvej_X3AzG;0qCqPy`1g+M``!sy!8*9~w`N=x?J&
z%R6d9NO|)4DVUUt%^IrlI6LRSVNJNDMhr!=T$AwiH*I*U2#;i3cH8JCoki%KD3$(v
z;&6<;28~x=>9eezTIvCTeA$s=EaO01$>*bc+GaL9G0Cd$S`E+Hj`l6iOKzsdF3$Hx
zhbSHA@sE4FgQPEAHZtRv;twCV<vCTIoqUV^kK0F0B)8VubDd>X7@h|_g_8e0H$ME#
zP$dzf(VsXTO-9T&v>#JbaoAefj$l5g;b_e3Qi=G?e!bm_W@9Wa=eyg^t1L4m95pdI
zDlW{~@^c(1eK(rwz8QKG&A7Ku#%LSPKN}~Q=seRiY=-GPb-2J7Ckjti)*NJ_2UM<6
zewK<|M4!lhka>|fB}<RHEJn^<UaOz1m(w$F8+0tZyq0CT7Qk5BzENI!Z^ZbJJImO!
zz-FP9o2Lc~^Y9pC{mY~tzbR7ydCufc>1$vG2S)Q7PkC!8dRZM;91qN#(7?@9vP>`0
zFP6(Zw~Q-BMFm)^W5-tYXKO49ixQY5O29vkHCSTn_3XQK7~NW_XX`F9aH;8H%gf6<
z3_}{9>~;oa=B&}Fue~3f`f<-QXo2#RXQ(1+e{&Ho|2Sg8xSFh$Ii1->>$ExsH-}>-
z_xZYClwB}qi?gtflOvLu`uM_799l{^=|KNgQ8e-21t*M%f;J1jmh6pEpacxHWe^(2
zL~@R5T5RAGP^j+@3sUPVdpk{T{7K?hzrFMUq-tqaPZdArVMia#lrcs18}7-vO<?*A
zM|tqFA5L(nqm&LKyu=!X++DYI)Q9$IbCgl$rg1MN=?9uJ^h>1&t-1*KBA4$uM>vnl
zIFT<tPh;2*@4|Nib^oH<Rl6O<{`@$SEVPr%ukM{GQcHpVQ1hkKqrXyFjsa5B1>%u=
z^Q-f#Wi5xFvN~s{U(OVx)}dJGl(4Zwi`*)(3)5R^J6Q8)UOr9<$fsNkv8f36<M{bR
zZSy+$)$5%RXo_+W6<4X)d7_u5s}SgX3b@(9Y}Wqf#X|&uAmeBR%HZWTBK9w4Dsjoi
z`l<OJpY-o7h@UX&(ZT&?tr5?B^)9Sqc>?;fbd5>OM$79+-7pGZViNv}j7Wt)Zgr1k
z4<c*m=+@QDZ%V9e{P^`;3ZXZo+gVYSR;va>f{;fksmhdUFzSL`IlMJe=O3?X@rGWo
zUuovd?Eu0(V&89r^OEhG^nJ*G<qqNqzA}1ECNE3#fp)Gj>zAdo#j~fhW*+t^TmF^F
za@BwAE8<|l1Cci(_WWJ7uMwXLwMwBd$sv)+!+cADsQ;NWiUART!`DdRziGkNmp?=N
z_@G%ZjsC+i<L%keSS;0>SIB~YTN_UX%uWg{kk<lHFaKtIy~s0hY`P`hKq;K=X8E{t
zkBM$vxUccB*Fr5VA;hvw?jJe;Hb+HWLKy`;Dm_WWznKNUBw|e8em|4ZOu#SydKb+m
z>4vg!!*3vcgulJ&FLBrjTL_b%2a^6Rxdw_see2z@hdry_2l0w5&o#QMVx}luVr1*^
zvS5{j$#W%VX#V*e9~(dmCo(EZ@_&l=H?;s}k_!`NPfaxT=eGFIJ)XaX0jLXHW#>>)
z{PQh;pBq4U9|Pbr4p9lgKlS?8uJ&Kf$O|Z5{{LSU0E!1;3Q>Rf@;?Wl_oy`~870~O
zU2ENsCKeL)^`E-@^PXE`U?TO*lkES9&i<(lcy?g3Pd148D-HWE9sP#}S1^G(&8^~i
z4C+7E_n$NM0k{nJCn?dN!u(UzW_X}76`z!o@*nT{hX7$f+PsNHhVVx~_QwD&MSv`~
zd4hRE_zz+J`J=5ga9KB{1pNO#fd4bKzj^OxQ2%FYe|I_mXKH`f22ia2|JJMB^VLh+
Wi3p0Ve}4x2lMs;=E)o3r<^KUHOWi&I
literal 0
HcmV?d00001
diff --git a/docs/images/psha-functional.png b/docs/images/psha-functional.png
new file mode 100644
index 0000000000000000000000000000000000000000..fc17e39dd08c830768b271b12dae925d88b7ac81
GIT binary patch
literal 11953
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
P1dx|jk*byW`u%?Z%)o}6
literal 0
HcmV?d00001
diff --git a/docs/images/psha-linear.png b/docs/images/psha-linear.png
new file mode 100644
index 0000000000000000000000000000000000000000..121c9b7c6416cd5de38c7e5474115d604fa51f73
GIT binary patch
literal 14814
zcmbW71y>whkcJx)Ah^3Fgy8ND!QGwU?gV#tcY+h#-QC^Y2^JiJJ8XZu|6n->W==CR
zJ>9o%)%!kGVe+zKh;Vpt001CLhzlzM00j6Hu>J%M{*|@uQUxDi?Zh=40018Szh4L-
zEdvJt;N;AOgyiMTY#nVK%xvvGO9%;lwzIc2F}E@X0N2$_B~xXkBP`zg%^N|fP~Su;
zTSd%IpA`iod@<t4sJ_6WNQQp-y@ILGgDN8O5q~%*^h0#CZzQGy4MI5FGR)qW+~|P3
z(D2dcZI3+5#rFHZ6K@Smd<W&%nRQbz-JcMW#hDdYeGy6oiBSIp4D}Cg@6ieP!I9bl
zD4*(#zBs&og#aGBd3dNvx?ws22-i9IPe8X!dN%_>$UE|}VCoMD-$00N$2bnDPrev{
zfP1uHAs`?M;hXu3ObN*O2<VL&8tek{w16JD&)+$~H}fIY0|L-W{DKLQ69;@oHx3mB
z%(#K_Db;WhK%D`=Fp=u#1eR$51_?D2aiF>h=$=G@uLV9K01OJDL6pEp4?u7D>sMDG
zFcrWMy;9@3q^?9cpaSnyYAsI-DW`~^)+gGZFluUaL==+}*wh$o`jGl*0(8A@sklsj
zEXaSZ#{nQG4imiE>sQxFq{_)jw&+GAUE1R==ywtWgWb3NsWLkO0N8f)o_V98ufy}@
zhW537%l&r#(M$(E$LT)8q!wAA0mwO8RlBzP@7{>~j%`_4+27k+mh2bQ(jQgxdNb|S
z?N)oWdi3Ubxxf9>xkKv5r0pm6@!?PJ_>FV{!BjkKpuzgz7_pZo`1cpWIg)+}gBEov
zj9mq^pV7i;k=INGBw>Q_lmp*p-;H**Xr4dtZLtE?7JLvMakRzSh9B;v$WhcCyLavZ
z;Hu5GXP)BI2Vb**?J1Y{3;tKJoNs`yiA4NQ0MHR8rBfcQ;~)A20Kz$bRMp?{Z+dWO
zx}gbrpw@ffU-Z}l1xfpR1yKayjC={~^(f2z1u23jstKv|=;s9pS-KU>f)nhJ=z3L}
zk$CNppY%Uv^-#3?!G8Qc{0UwE%W5cuLAd(Y=ug<GK@VSg#6O}%kbWKs#ZVxTienXL
zR18=CtRhZ$#cL1A8S+E4HI922VDf(nZWm)r^s80iokwU8YAI&N3lz<TpEh!2OpC$F
zNuRc_$K#D;`+YE7W`?{P!zVPv(0zyl!`yGhKsVSYSi?aBn_xIrLsE`VHi%cPTK=Ie
z?ACCq#^ocLpGY?>+ea6{&-z5)#nq+NWtYW^KNFC$psvEQ!+r=<=p`pfD3+=xYejwR
z$1z}H3{e-S`MQV}gHDg)5h~QrPKp*L#6;c_3n@{PuRM!3D>`eV`1OdUB%MVZ?`y)y
zs*z<a3}+(EXX@dgz0AG7J?1_9y)Rc<aG3@IKl2}yb|@4_EhKUGQTAE(p^bkreOJj#
zQ`{*2t&GYVqbXSNyHT-9A*2|c#VL(*A^=N5s-Pk_X%5c}+w9)F>d>(jbt8#LHf36E
zcI-&(Fy-*WjSB)|FlN9|s3`?*It~nuDXt4n)i3En+_?zcA!P=3#*<$MsmQ6eD(X~?
zRGye|qi{)*Nn}a*RP@RvrG=%NrSK}(Dr3qqB|1u8m7*%lO1mYn^T}l@rJ3?4O882q
zCEUd!rKZKU%KZ7>8n0o{8hz4zazgnEIW@Yw?Sr4;4RPySX}(w@mIXWcvG$YIOssf1
zQ?>niC2Wh}EiL)YDa0(vtX8LZooK=jv-|7kLx!U)>;Xkl%C&d+CdLKj4kdmei*yU4
z@ej+=<dkIfGVwBnGO?2mw#u`j%)$<lHjQULr0+wL<Uh#8Ok*aYG7pqils1asim+sO
zxo#`zN-YcUf42#{blDW0|H|sr@y(L9E!uSJICvuPqJLF>wSFqP6+=*mu0tS&UPG9~
z;Td54Y0E=MKeTqKAf(+VAXK2Aq@S`K7}qkxleZumC5jwrKKNsobk};&dN7X+n(Pai
zl+3Zrd77e3OCe<;w=}o((8Tye?!;m$YdSCE64OEYLHbhqR+FBlt0qljabvTwMD3nt
zp~iV*yG@WLr$&Lgil%m*Xhmklx5c)Kwj$J`7TE;ZvaChZzUs@yk;alH-0J;h=(Wm5
z>qakqQv+<%rh&@7^MsBBuU4<9S6&#zkQJmdLQO(%hkAPqE>*70w8@Nfey@R><Rf}h
z^(mC8W#-*R^fAhQ^Gv1mIWbdg(-wz->(GcWDgQCL6h69i{K1Xkjy*}o+n?Io?z6X<
z>2>M7XT@t(=WOTZ=OOFa<1E>fSsKg^(|yB2e-!p-_~EmY7%aESz2$`D{7f4TzS0}g
z$Ej5;RW}v5l-}!KVDsJa*=O(a?eeg1GHq(;j<a_+4L6O+_1R|W25kxXe0?{1cYmJ&
zihRF8n0^TJ`|hU&`TXGS`K2qGpKHzdu6E_@dt^?_cg*iG{uTcFJr!TfhEHQFzT6-D
znv9z?M+%bnK3trJ(f_L-(dUgo9uyL!7R(=Q7pjgo!<fSAGP5q^uqFH?oGiSVZptXf
zSw$<!O2t=7XTh_|-pbO-KS*byF}|RlsV-q9MZif%Rmo;!)w%U@b{(>lxdXrJf&Ghq
zSliC+_hj!)P!U!M9U2W+vVe4`EJxzM?<iEoSdrhZ&|SVo!@2bm_L`E=&#=veE(`sj
zB9grlr;>4xKaFc=bt4^ME}+?O2_!FxZI?!r-bm-l!b)@gY|X^W)xj7L9~b*mu=I;e
zLZj)i>0cA)v2x>}+P49lh$ecXB$yG)y4Z3k4O+NH!NNmjO^PKdm|9a~HIuH1uu;zB
zvMlO}v+=sowOICyi|qF^v|hCB_{M@@DK%O`^}ikE7M!&_Ki$^gb}^x-gH@r+d78r;
zsjL^|%FfhMD!n_%++{5Nbb3bpdm11tPvBMH_Jh1m)|bw-<<#jlwi@)Gf-~{?FvG$t
zG1jnCFnyLO)?N4ULu^O8Qr8pfOUn9NjHXOxO^*I<(q?HPC6}iBO+m6jTv@G0+)}MS
zyS)=xqfeQjSZfPt6l%%q;%RO-E*hDf;O1A(SH4kxQf51!-DuEXda#)}$M<NzV>w+|
z(`vte<s0c-Q-M&CSuj~JewKKyyXUVAD?NHhezw-GkhT7KHuPck!z;{Jq{gL|`31sR
zUS-9YMd}kVq#@$Yx6BI{T0}NPm8gutov(JnZhJ@fuv_;;h+M1AksjsSFmuGtgr<b_
z7J_M4X`<;$Y0p{)TCH;9d^3y3o9-`SYsAPIEIb-+lGn;3=Br2ka|xzbQ<0fTnO@#>
zkL!ACxs4tNhLc+s$hH@)D305+BJU9g-0j?xKdzb`uWHx!(bbyO(yF+0t&bg#dEOG{
z<c8WZ+R`dpept4gyLU8rnA{)XXR%Li+;q5IV!baeWO4FtbX>dJ-Vfa0ZeeYB+mpXe
zj<v10ke^qy%eCv?2%LRi5!wh@;MaOvU%puPvFLWmxt>`UyN3=6n0kx5jX@TIib;(b
z3q}k+$>QMS<lN!6e?59B5}GoaBFn;l%Y7TG#KxlceponJnw<GH^E>4#C85jOv*7i(
z`vkXYZLoKcsB^@XnNjCP_4%yFW!;7FB5w;>ZqM_x55>FLW6iD7bkTDHZbHKQ#}B`*
zUksUP*Fe4b*-%_j1_0c@0f27+06e~fk4FID!~g)tdH}%n3jnZf<8=o_0e~J>LioF~
z>*{Hylc&lp{?OLJAeTn%XEseX%I_r#9~1-%Fsd2E0}?UhKZ*$CqkjLUA}J_QfS-6C
zON1|#%$~hPjGq7z&298TXSeC|&)^{AqUGRm@PKFQz*7h{t_wm=Sy`EgT@eGd2Eb#b
z2cL77<Naw(L#CpN`L^VQe3EdnTobUjXT-!bdwF$LsNWa-s6*_*nk<9QzH@%$r(U7#
zx&tejNTJVuN5JJ88<9e%&z6dUalBL&5)v}hrQ`E-L+O0B9+aKUPohetQX=Tv)%BV<
zb$8ZJPO8U*clqxo|9b$m8O!^*8PRfAcAi-D&hANoYEhm=gN3Wxs@T-L5mSxBf$Z$u
zoJ5CrW_PYgiBgelr+K6G#%PPf!N2?ap_!2|Q;S96s=B_vWF!(-D2i0=i9qg*S-$%%
zo<W1A!&D}xgX&_X7WrDEEq2`s4GBq^S_Kw4x#>?wM+^bc7$QTpyY|N?e8|v%&F|sR
zP*T$4DyXQBmqppe|NivMR_XGmvbcr+Xmykj7B-p4`i57b>WCKw)ViN>wbd5=bgTz*
z7Y<3OO8r7ZNlD2@`y~>Lx_u#-?EZXC<#w?-zvcC~!;rT>TdBL3YpeOjNvYuv30ZfN
zo*Q?NWt)7^-lG?Ld$KgP>U3iCe0OG0qn<z4b^-U<H<3n1kqHsn!%9>FxdKq8QBrMR
z@7RmE#ou3lyl#Q4_IgITyuL*j@D~y!rR5b87FJYJ+MhpSX1dw^0y*3-p>#Hyh1}|b
zEnwn(-;we9d~s@caX(xk+>%rxEWzpcP@SLuBPF3|N_>cY3qyd-dc{KRPFRc`4a(?b
z@yz~m=UZ4*8`(lBuTwhj2KX_kalgvc_LncwuauLhaz&_NkO&*`wZL;0C||}a&hv{q
zUpy+&{b)}-czL))w?DhQzE4?RR&Q~p)rltJryCFw99SAs8^<cshU*r>e^COWRK=1?
zRVa1Jal&&M-ixwJG_G;ccB&NSmym7g>4iT6?Ck84K_Lq5t`q{D=ZEhfGG&nkN|*{L
zG;%+#IiKqF_E$mtV$dfcm&+n){Vw#zchA1t`Gkjz>>?Qwf{Ld}vqmIRL+wFh0uMRw
z+RF9iOApP18-&OGdCySWC#^=S?R4|4KRI)ZK9dBK*<Av90>J)ga?i{NDm)ejcb(XG
zc??=Pl`=syal0%Bbn-~@>8Wfu<FVc2Q~v>rfu*I8E90@9^Rploo5O(D%YSgbq5-0Q
z^NES;hPsgiVYw76<}WlQN9Gjay%h@-)MK&KpMz!#1UY=RN$g|xGvl%#e7`U!RL6fS
zQEp+nXn$oZkV?rtR$2f!T<)ySZ=v&kSGR>`aJzK=!IVnK?4ul6*+<u*io7G#DR|HM
zK3}Pwevrl+BAVBe7&r0=e{l7Zr8<LEDuYe0J!sIdDdeTpoRyY*@KDNX$>H@Ef%xuJ
zBnWOlG$umGMM-zdf^ltQ>~9<jU~~1=_M-)t%X$BZQc-C6!$<SfRElu2t@@zrLit~O
zUR;>juKtMlY#Y~J$08y>U;1J1PB)|KBA5Ygm($TZG|3ciJHavvPaY!*1%=z?CR-l}
zFBbbv@9CQr(^PgBBro^-QKZqq0e!~wnd2K*H%zyjTa(M30cFoza1&Owgy5y5FzQB&
ze*gV*&Xm*ZFAZH~r8;f$+SPVft^2LTrrQDGU?fo=a-B(?cONvJcI%BReD_39?u^CJ
zW(RjcZ(mqc6z!f#7QfTU;`U)p9*dcL44d_;{mVm`KX#;Qgih6zSGp&+A=z4^^}xhR
zstIixzq|*SoTmOxq!%j|F!A!8_Uu!uoj>Y?g@uhj>9h6m6Go3%6gUSwC3^e%L(9LG
z6mfXJ;K-!&NtGp6aJU}I`w5>x56NX1y*}}qtrgOC^6_PGdO%~VrL5Z=yc%8qr5(@U
zOz0%OE!a)BozB&8z+*KV*0SyBbJ_Bd({z8@r2<yWZ0+mn-w&o}W$@U^*w~_7Hr-N0
zBCr%YJvm#QJYp;_FYg_@`oxf!bA0%vv6vC@MdsR9u94@nnz%Z9;=YQxZ4ad2@ayw@
z>FM#jIx5QF+(BCFy(8pyt=q+?(P~W;=mPj2{t0Dd62NaTx22}BW`AL$i?-Qlt=UWY
z#)FG1ky5$QVs~lach2l~MGCY!p7_VaAb$#72p4sDZ)2E=!k=r<a?$bGMa(^6Cm|&b
zL@$!Pdc9|Md#-3I)~>@sCzqviJ%vp=?X2(Vt~DMT7MJVF^9@zMytx@PVu_DS{iziz
z2@y$#{`>cDVKK4Yi;JPAE!l%8_AR}CIp3u-xl)bCQZ65dQQP01PT2UD8Z2S!E$5>1
z13zXE5<a>vGo;UIcX?+Tk0q0+es2*XR#w1R=j9QXl9_PUxIl4aPL&P}3R0-j;iXch
zn3~m1t~NR2g1)<$s{Snmrd&GR$d?S&3ayog$w0XMF=m7QPmLGLJ;_n&IMZGHU%q_d
zQTXlIiBz{>VLT9yNlHeRyL4n9B-kRsf*~?u6X+6)3I!D~BXE1X5EdHRy)_jxl0ZIp
zdDiskILy$Q$`&L7k3C)G<MVWP<hAr7BP**v>9VCzu1*2I;VUgKVc7y)xW8Q7^HxEL
zE`9jZZLa<Gj-)h#STuqD?h_)7ZcWAq803FFFc)<u6L^DOywS4-lDu?~IqNCPqIq$t
z%qD2~9+;UrK0|QoxkemE=H@@zusnvkqkHsnWHVdA+j&4#rd@`G&u)`%n;nD0?97tw
zb!G1NF-NUxlYq||2l3xTB(8FW;!2_8h=hc61_NrsiodGIbKP-07i2iJ!~T^>`69R2
z1|sx_+Y|PDoep<)H})A8a{`$)Hu^fd8OYAeOY2TZJ8FG>eFOpy6x3qvGPX4rE5plN
z5gx|9UC*&Oiv}j2H_vEd{^+;DtGIN<bu-`hI}uW9>IgnBeiHEKUcG@zMg8r>{^|B)
zDn&PXr>rK=8qIgP*%Aj)l!e6eYJ@z4=O-Gwnp$mb?crhvzTr^xz{Es_yeD3isF1iF
z0~pyX=Ig(Z-93l%B@$AZev)*(-cftpotnG`BZBMKyZafiPpLCdqEb^+OMY*K6h2>W
zu4{9OKR|S+#wxpQJoeZdR)9t%>c1)&`*(X;V7k@GrgeAw06U(^4R0zYCK^T5XIa&0
zQTN#M<%`v3D`r&g`lW^l=|QvqXBR8y|2|^I@?^<YZ+v;CT(c!S=Z{{i^NC3Uty<-e
z?U%>vhldCGLTOwKs8Z#U{yV}o1{@~q(wjQdsma&(E?D0y`a4K<8m#)&_VdRY!y(+~
z1$C3jUw&<E+^^5b^%aX@LEW(i{R0CGG(*(X_*k-nf{=4XK4YP%UmZT?{G-If84jHa
zR%)`*=IXrTV*IJ*);Z!}wbGI~{U^uMDpsrx-p&C<v}Q(V+Kh#Ri{qtet7FBs*=`#$
zPb@}%Ha`q-JfBa6_yDcgE?o1%n~*WuW-`I$e)oV9mCN9|Oy2(f=E0f7qcvNf_Hs6B
z(a@xF_iixN>Gh1uW`#4BLN8RbFzeGT!1q*4zp10cw!-Z57ISm97E-EGR_k)11Az5X
zuMWFt#>~#q@x}ITeUG!h|A%q^FsgJ`;)bpFYr_&QkK?C;zCP<#wVG-9WSVEF3ekYF
zGI)G8s~pRN$-s|Lbyf>ho?c#W2_f#bHAQCL+8t@4w|N{sM?3*A2u6#i#8<TGVu}D5
z9)P%{<mfAclMfeCV-2{`(|DIK>IMYsuxN2OJwKwxVOnF6_%4(!LCW`U1l(FKR)d8D
zK|{mH*jS-b8rNIr-}Q&FsS%~ZOP%{l;O1~9A&b{Tv0UBE@1>5MT4nSu6p66V=lzWW
z@?_D(C%8<bEO~-x<5h2L(OQ_@BCsb`WGqFK(e95xscM;Gjz@EIvpnThc4dFi^#Nn*
zM82sp8m_|SyXt+JvUj|O!{6CLCu;AvBe6~I1H$9Qiq}IYh<*bo2>z}$^6m#HXf!-L
z$&u>nwWlr{n@aYUo1nhJD11tlLK@~mxgymw&Bg&zdyJ8>G47!t<b1~xMGkJx8kY+q
zCWK&ud#ntC8+H}p1D~__b$T|NRpBT+IcAs5ACfB%!S(8OT|v)JMlk)k_^kO#2Xrql
zyD^b?tZ;yjk5BOJ@x=8MZ;BW|Yd|^QT4%XL_wxGs_||q|zFh1lV_vRGP4Z{^{I053
zJ69OCy`y7fe0<dDofQueD`MZTF$%1eGp#aO;KNw`NWvASZ-_IU0H|gL7Dhx0rC&uC
zZI^$UGRcd&x8@fXN@{ARfsv1j+G77rG?`X6i(A6*C2%C@&I+4e2P0rcIfq4?+X+n|
z7=e(CTCF0vx!KbG^~p&>RwC{u(s5*XI5sj8K|)S0<t7q=)8TJ9&7*Ni`$I20<Zy6Q
zI^0B-!@(prhfH5EB2=ucsV6x;yY(dR+ft`jt@o?@O1*hP2A>1l{X^&Lv+>N%fa32T
z8Z$Y=Z?7=$6IoIzbW-l_trJVSUEbP~fq|hhO;zJ*ykd<uYtCz|WC;?Lx?OZjRYl<g
z21y$pcccD65v1K)x}ILI{TWKg#28%_KfbwV$_o1X?_DKP$7~wqa5)`^c4cR~y1PoA
zaXDRo>dsVeGpTTObCZyt$=%uB{sLN+I%<zr=W`m7_Ktz6B{|7tgp`OTX^xg8@Y+J#
z+S)J>5iscK=~t@t^R!pyI<-A6Z!b~h<mk<p88i_@4Lg^7=Bu*7pc5Cjs}2kd90f1s
z)O1i<F&-@Alzx5?JLl(g^bJ;SODvh(E?C&u*s%YuQ;M>^MVXlEh)$Ww$)$p>_Mu{L
z@!uP4NGVC;Kf3Z-Y5O)eb0BCyN0Na}3E7V@A+g!m8F6tv`%)=Cot*`R|6Sb;ZftDW
zoJvSblhV>6mJPst`rgySv4@^0Eh|exM~8%st%iZo-riy7<kW!gVPI&;h=cHJg6zhf
z7tE$+SGZ|}#Kdx7POGe}G-J{9^bCJF$k}@BHK;)$CXN{~BOTN09vDc<$;o{z3~R9u
znx9wxp{+e*(eUv2{Ck0Kndm-(zN5dkK<e>s4Y&Pza?Pb&6xkY~yURC1_rDF;DsA4@
zP$V8lf<f60pwZJ`th@U0qM@M3=bU(Xd0pP#Hb`mJYg+rAQQ~0;&%9qdw6&PhQ#ia9
z!a6h!(8(((xRFYPw<Qx|++V9f35e|f+<6ItKYg~OpOlqNq*YVJ1Td3^!Y0z2P#n(i
zzWn~3NU0_If5(VB-;sO=qtf@<noFqw&?MvNMicdcRqpbiU6ISh3prZ}WKQl?ti$zs
z3a7&Xlac&gU?Er(bB#vON`c~Hp3!w2Xg-ruHOHfQ*nkn?Hs`ZP*MEQ73RSQ_f?sP`
zqtO!zbTQ#F>1>eyuEx%O@p>f7n8RxW<0cO0Jl2?)NghIZGkR>PEy*ZylJ-n$y9O(@
z=J0LK=X)_*K0`)~yZh&p9>m_m|F-+AJ1@M@frORuxIVF!21{(UszJM_aa=_-ba6SU
zAv2cc+u30%D)60o3l_tpEOz@A2%-u9xjcudr{_l{`cfid#6#QbaD^6^w<-q+P*?ZI
z@YDVo{vB|-(t#f^Qk<L;F8O8q@Q-gw3ii1T(R`^=`e+jM<!PM^W%^Xpn`iTV3joR#
zqvLsV8r{Z38lk(t7~e$#iWTypJH5RFlPF|o{-9+1_z|1YGEYTCbsrpxDTf?$I(Ts|
zib||2c%^Y(Hr)!SmL+9%xHEgLveY7IaBy&3Nv@@s&(>2q<>h{A8#9H$#Ke65EdXh^
zFNsj0*<f-oc?Q&*&n3UTJ}VXYz9NCQEJPZpEGnF-HKukxTlK38_^?YRo9|F0Yk^c+
z%!33u-6lu;-#^MW{oMHJ{{&&{$~(x3?0*?5tO6_-%lB7I)BofwUB4pNnQe7ura4ei
zA@h&0d1Yk3O|Sr~PKP;c-k3>Zp>1&8eji}e>r4<QCnwvNUU^xEK%7Dj@nE^dH_Oaa
ztaC;Q*3Z(vzrsg%Nr8hmKA3KF%xrlFDKP%feQ)YddH-yjxk71zUsw>$7hej#Xuqz$
zIy`*zD-|$c?_9_0yce3L1%_NYpj`3;SB~Aq`FwNYoY#ZsWW2TJCVssrRptsX5g+-=
z2Y=$dOdfM2&5BxM{aL;&MYG1}2u;W5713nksfUipbG`ZJk50$b{Cr`-2<(Fd{k|(1
zhr{VFodm4mV7;JG-5yA$M^$O6+`t&@4T4{8F(k)LO*O+n6beQfabZu}TB<Od&6h}|
zRzs?Rv+aDv+8;}*!}lPQOY5)M9U2)O&sV?PK_Gfz#GB}%hhz5H<nh+7@t-#MeRw15
zc(fWc9jn(?{f(J9Aq<@i&4o7Fa%m?t((|e^!de!GJ$fRYU8&Sc!!!KhpZ*jP$KmZ=
zAw;7LjQ82?l18g1B|J9W=T-%ls?NpjO7qIW!T7{PWr`$41&mHS=HM|##=wverEg!+
z%RZ%LsDyYw9hu5za)qV1pmMn!2L=RWfhY@!kaIMcf6?L50s+EL<V+Gsrq}9OcXOar
zE$0}JO6(q4No`)XjC|Q~xI24}NZd1`QYjTaS+q7=Jaq#XlEdi<!RO@-#vJ#E#cX}K
z@}pi)Z;;hyd+Ka~)OF-QxM<$Lp(n)gEY=7^v6w%Hhr%G`IDDQF3;YP<@YXAGN6gco
z3kA;@mV~WqVa^Vz$CQf0Y=N;9k4C9fNFzJxcCXj&xevEBkpV&kS9kZ>5+!o91SJmF
z8ypa>fea-D+2gKWi@m#W!%x?{AQRX*+Ww~1WZiXgYq?aJ;Oi@3zSS8(^P^rp(q)CP
zF-Mt7SLem+<r~>uTB!K>dAF_?t1JM~Kd>O9sB~@f;q~ms_G2t~>a_)%)(*bIxQ>bY
z!c*(cy4u=&P%}b?>J+7PcjvY^zc$(%+qAyDKEdlLrSgd5v08oBtWb?tQWO#1oBsWE
z=kSo!mxGHlEFmBdQ0&qVSf^bV5k3}Mz=WyLK_cQaU~l|S9IR9`P@-xo)*>|7KELV5
zWVIOQEgkL6?vJ$`jHb|1Z*Ge8+ox=lz3bu=ueHlA1zzeZJ&uq|v}8$-Ve1&Zy%1k_
zY_6@PkIyT6r}4))(>E1>%ln_G({6L#!rrdcgsK}zdtOw-2-5H4`>j@$<=WbczIP&4
z0%|U21T0Hgej@IZdrJ1xTF8Gx#6BQI!veguTH=5GqOSM&=7Do}V_SGYHfO;av>MZ~
z^c-$<QCc=<4x!%RjtDJ;wf#*h9wobbl+|+D(&==gGXb<M2ZhXdQNL(R+B_6AEBt57
zIxFxKvf_G>nN8&z6pbx-R5H7LfqKm|{{6hAycx4own@D@;NkhXPH*NvrxY3yvs=Nw
z1)4XV3~rz8Nlc)przcMFo1|i?5ss;BhEeZBmD_JO<}`NOp8S!77RRG2pCgzYirA#2
zBoDLOW0m<*?exF2nz6s)Gro?xF{V!hohj5<uOT53@HomHMGc;QTk!YyKb-F5)oyeA
zZKLe0_Ko2)3eYFRmOhazSVelmZnf7N6ajT!xN*q;f#=zZMXAWEul|S`tnI&DFAWYI
zHOtA+!@^+Qs0$REPsGkQp0Qz&2&k%g@kB-%4xm9j_U#*M60*lFX|b6?JX*r^X8l`1
z2YskkP6nMyDMmV*b)nN*BaSrLU=+TXV;?jE4o7H*$NRWLMO76sg&qSQW2!W$pcKj4
zF)C#z%XOQg@3%Z+f)S7B&Xb(W)h{j2(=T)w@uDJe7~?Cn8c_}}#F9roJ}T$;QlW_`
zs5hITCS^q$J^b4?+MHL17c7uW`o(Qaq*N$7Fw^5VKhL6Cr3ob<Y_u2PAdL}J)kP!+
z@~2-+ZpXYHD45i$`BDe6EEe;C?_7~wf;mHugJZtgbimn3)mC+uWD?2Imd|H%^CPI5
zzl~payPn|a<>X3vZ!uty3H#^P;3Ecl`vm<87T4Ayg81LZBXOBaluMY3rZTo8ro<Gh
zWC_!n%zDJU_zggsTCUlEM@~+jh)<UgPbmFe;S(a#Z)tUok`YQ8o#xoa3Qfg26B#}t
zro^thv#-?D@TfI2)}x)GRZDZ#`p)~|a^eq5kRB+GM=x|B>oOjW{gOzb1D?>tfaR5a
z%COtlkAT}PBgYreaqDJgf<ZWxQ+MUq*g6q4G9rygp=mkr$mDZKj<)R($=>XkIk|B>
zUW`)Q)_-KFd6qj_tOzSbA1GGHR%%zL0PkF%l~SIH4Qf0h0ryXT7jCCQaa7{U!GYgP
zyg#(8*Xyco@78Q<oYqvyWYT)2=sN;MtM->Lsd0EsSSqxda^<FonmM@h7LKplWiUi~
ztQZa1(tq07<yfUM1txvkUH;wY$@ZdDs#+o#f>ibMXm%g6MV4LH!-06*nYPOZtSWRK
z4SSFL{wmuWE?e6p;c?}f9Zy;3_t*YVFaI_W0L=!kRH`H@-f79J@i|rw?^BKhGP%F=
zB}(-+Ai$cLvD#>@_ycKog~9Ln&KrV6*t<3t5sn&%+&&wUMAI`kf&b{%1G&!2d$?Ia
zos?DHzcT=Z-Y9`i4mn-3o9^o7{?}PMBO`+d58^@2e*bt!@cvvIq>Ui(CNf&8)F$Bc
zO#CW_<Z!eD6`87GR<CKJgQhMlj{%h_8=_jazf%yApI@+jvMW{hbQ@~39*D<kA)i0|
zn(CovSxx`-YXGPbz>*bsjzneCp#BMoQdHE0Ya~qK-Ia|UR$f&VD~U?2P;QcaM{TvE
zH-f&=XeS?5n&6#viq%@ODystr1PSTc?^9mSt|t@hBg5mQ?M56z7fhSm&^0wR2zV?g
z5i9Z9&`miD6b~@LXxR7xD@N@TL_k0f$g>(A{sdGW-g33NoD7y#b&f7G8a`Z&(Sr>Y
zw!RQ#(`rO5`Hh^xxdqUSe6<8?{BeF*`}3sMN9d2!%|G)z+f1+`z_c3t^KIRYfPlb;
zUTx&)QbN{A$;Riqk%`Id_JW#QrMVKY+Gs8WhSa0UDod~rSH@z6)=a0D2k0JM)VK{Q
z2QN=%3zW;{v#$2X9JY4~PG#)ukM9k?0PNRbsLE~5vv1To;aBK-qGFSi*K^UTmi_tj
z$5(VF_E(0urywL)At*q*JjHG~2u7Z8fu!8#JD(MV`!iMqRKiH&bHV2rAQUriByhxN
z(2Om&Wx-9cc23I%c9fHod%DS%cru%NYL7Bux&CL~#FQZe&e3WMJSc7+ur9Y#jHNDH
zRB)1fE<DmFu*OZ8@gi8CxgN=*RPuWC7z`M2YBXh<4wRyKq4OxG^yQF|p%L-^)7I)&
zV`xa&cA?EpP3*VFA|RK<5JMt1dAu^VTCM-023$o<s?(^BV=@1FtNGScLA`Q-`OO16
zbIp<ep#3(vc7Xy8EMEKbBXg0@Pt<p3Yo-Z=5+f3z-15ohl>(ungtU0~)>2614T8l&
z<-}i^bO#-SE7wom{~1jZRcg&B=#ELhn@AQ=43UsvP;11S(6@`1snV9HRq;(uzWbz%
z3=9N?anfzP_FC2aJ8NP-nk&M_Jv#cYLjj`5TH1;gX)v%?>P*><rBX~b<@nK26=wc!
zAt4~_g%Eo;SKZ|o7BD*B;D|=yi6noCNYSwv@rC$ceaw3C>OhabX#1ImCnK3w3lb%s
zd3q?By-+kye{UG|zGK~VGGl~1+p~8d0=q=3i7o(o<?jTDt56n-86`$wN&Ct5n9`=h
zAyuh!YD(~*#NmA@$q$|Ok5!mtMEwH-N(eDUo{`Snev81jcfi}a*TkRPz4|aMSYRg8
zX-mF)zk*5(15Ee-oeWg`tA*i63?6qsI^W;8*R{2eHkyc4%9Q`^6pY~@Koi^`VNhdT
zb?2Jk;^Km)KOKZX`op7pM@8A&bKBWy8^v+7J-DAe2)c&?V0I5q(y4(E2fn1$S@rWG
zEo(L{^#*%PUiaI*)6}_-Ffh!Pi&mhVZh#y>T`bo~eZFtyf6I}`GXon>HQs&1plajU
zgp5u6B`&IprIKCwJ%LQdY^4?xa};~B`j1waob<;(y+KmywvX|4yHCCI!MMz((=AHm
zpyXw6yHaj-Jj%G>c;JTZj+!bRjFfi2e~6XM+#KmBluoV9;Q0B%AN<q0=-t;3WV=})
zeZSm4q&J^wZ;_cvNf&tt!q(B751nekB9@E7V+EEwJlJ)zvg)l?jv<0f>ol6p7|+%^
zBFoC~6UgPZ&ziOdXJ)p~u|{NW50c$YS<_JhBU0$|Caxbf+<2gJgu`}T>g^yvH#))0
zu;bmi-++hM$=B)T9|1U>ED4?DkTX<MxO?fKZ>(>?ZSacA$sKguZynT4@%7F1HL~|a
zp*rXg=>TB6Dj_hCqh6C%A}maOAdPTF9;3If?;W;(lZmc_!Oqbx|J@hDlg~c?Oh;bU
zkWw-K6M%|I&E&q$@pt^mkN<r=Lbj?%A<yjT=4>oM?hT#W-p)=SKrv@o<~zu${!By@
z;xfCl@bU4nbr`YWA-Z>9xv($!9NA+QfW@-8wRJz)*tzA{esof{#);0iL!nmvCq%wi
zh}wPxedl;4yd5=rG!d7h`sRCe$b5;47J$p_{Np!o`id2$T^dqVJBcsPR(Z<}F@t<<
zEyANtm(vN`(c-IDSY#-Qz~b9mh<1{k@<uD<uw_-(7sEl%B<{^E3rq<KiMaXsdY&bE
z^=kQ6$1^hT&Q8eTY@ajgdQ-520o4kQ8)&?EdJ0!9NDMV?CQBp~t+P&)uQ-7Cu5u@5
zE+QqR31`BjEd&0aU6f`sW$(sbOCi`1jAky9-G8oZ{(1g%i{Wgw77n`anJ7GkTH#AU
zk52sEYk0v&I83wkX2vC@_?0>j_DfjUk1&|8ODE{)J1Z@Q_z-@6EU<9BYh!bjqZFk&
zycrppoK8C&U>=G1&%JzC=-x%rnF)eF0AI{4r&1NIQ#3Tu@Q(*y8v^FUj0G=^#adF(
zlP3h3sC!{xztVg%i*F!Hn;T?_UqDu(E=_jhjDzzswH8o@ku|)J{m^>bzC3e(z|9-M
zW3)AN;gO|YL4g<5!K+#;YHe{hvVk{Nad1}hbK^*Z=wJ|e*>KlKp3w+&^&TQ1bHP*r
zzzGFq2oTyRfT%{~e~<k?4%TqfV8Me;%Rh%Rc>;H6duxq0`+Fk^p`XYSK+wbP@N{F|
zwy~hP|CUqv=>`WJ8~EwsQe;xWRj$>R2I46m9v;^MZ4d7Ze&oC!-@F8La7!5Pk0x0J
z^R|+n%=5S+sOT#E;&Q@+fPfIV({V;8lm1LX0tr;e4h6!ZQ)o4or)iYJ<XjcUZ9RG3
zwJ+w3zTN}#INgTF5X<he)-N$^|IwjhkR9db!uf`WhyMqcs7e7I<@GUNOb^_>t761P
zHv(v6UMe=edXEp2??3rqFJbfZ^Z)FgfM8SmYUAraPy&J74H$Mcc5q2cG|I5R{8t0-
zfgz&*c(o6@i>&&2WsE4n1KCUmm&Fcrn7a$pquGMy)|TzVJ>hGU2}*^~XF{y`tS#^7
zD6o?eA0O}UBLLWT-8y%AkX7n*q!DsE|2aF0k}b+}N?!zJ!D<k1YHBKY&XmY;1jYCS
zN(GY0C0!rdEtaulI^%c053U{_ySuwWCv4W>9<Lr7yqP{jvcim0)Ypdu>0RgS-pavM
z##W6((fBV$A#afMg48}NbQt7m-#AE>J-s|X#?IsottQD>Yc^pCfFzcbq&B{Ph&*(`
zB5AviKcTo)L9s>g+kbsY<BLsx5n-dZcDJ4LZOYBfO~~O<70c7nEbznj6JuiP%`W3Z
zLkT!s<+&VPg+LNR1x6H;;~{x`Mg}+%5&-Q(vnk>^AW?-aaCiDT=G{0gBN-3ycm42K
zZMcX%@bnb)A5Z00GnvZzDwRxw8Zkh!(bh#yM^_0Mn(gCjgd6GH!u?OEjn{P{RGjjd
zm|`e88zW&PqmB0gOwpj_k|(%zr^M2valyAp7$G%@P$84cpwNsGEtGv;tUP@zmLr}q
zZ@4<KE$gQuF*i4#t@QGM_!yg$^BID4nqR>Ae3cd}LWGH_E+3@V;Bbo(*q?AVmP;6%
z*(qKc+d7zxSfIKBQ!i=0nF2)r*qGFhOzn@ci`J|E(QKLk1rS^meBWr@`Flzhf<)Ya
zuQfY6OPc$`4VIpWE~V-RW*=>o+k7!S6iTM(S3f_I{o@67(3iz$#FKy~Dbcq(*Pv1T
zR1qLr#qpgn>(^u1JvfMvEfP_{2u8r|g{QCoeC7_<xhZ1j;2<<(<bvSHMW`9&pO^O)
zs|>S7^K6u;ZX|NWpl4tK7iziDi<^Hk8@W6FTbJE-uL#)Bi7fkB6G;gAXwiVWgs)tg
zNM)HTAQ(w!{3VTn_(@nn@BGE>M|jxpVjsZtoo}c;+gmuGcQuKc)9IKc8p-`fMkYg=
zOulj9*HB)!5io?}lZ;6irio!-yv{iz7DfXvcPTNkL<`8Ne=A{>8;BImZ69sN@wSYb
zDF^rl%}gm{h|5h4^EQGVgwmzr?~c2J{p8<rXO5a1h;SX?@)*j%m_FNGZ@IotT-0L#
z{_LK~gxsASt+y~wr18e6mTiZTQvoRW4!6YH4C(N^RZSPm->s~ydZ?1)wHp-Y<^Z$h
z9Ed)?$HW@ln7*~K1Q3$$g4A?C?=u}6nVjJqRge}fG7(pQ7&<we`W6cXTz)~p0Vkj3
zofVyKi*!||*MCDYBO?;vICA=F4Y>Hq5EM7;(Idj|Zy%Oho$w1JgY_9wr(d#zYv?rV
zf7u(4F&Pd<dPHNXRj5X_T>oXXUS$E%JW2K4{T4*Aqr<-|h<1uD0^Z=-{n5*ls;&)(
z`j^zAY?H&-81tn{LZC=4n{3QXc;@JGEH&{aN4?FN5KMK3JN**Bq@hr!+f%I@;O2^?
z2POuBTAlJZoL_Kkva-Ojjr4-P%C(8FpMm(39d^q*9{0@ThrqzL#^_#}WHxI}C9t`)
z>2<H&E0qL7Ys~k@tN>_4gRRakI~RxDBsCqk9L{ynfvMACfv`g~Pjtp=t#LQ&!s+PB
znD5b%qmS<mM<j3hYM(8!&3th?!0sj6dN#1uc=Q_VrK6*wf)p;o>h{CcOM}n5xAWP`
zL^>h2V*gMGd<xz6>7i@HVFVR`Tq+f7nTSZIrjI2BUJ{4<DTQv-b6VF_*8TvtmOMC7
z&}g-3FL$riV!@j2!-wXJt<|`fYMSMpL;njqjs0M!K<egVDTe>;A#=6Ca`q(%o7455
zyx)b>=`v$5B4KZ`_1Zt$9ig(t3iv&Vbz~}4Pyb!=XeRSnQm{v2zSfAiP^xNt*184n
zn0>iB^x>aP(PVR5OD+YRY8hsQ?ESPWaO@6nf)UK<cqkvAkZ?iqnMBa6X2-}RKLLdp
zxygwh1N0?vadH23aKTaxwsd1t)*6j_`@_alc_WI8DT0yk2d94vS$S8&W7E%+i6H}{
zDb!P;Q+#!l+6D$BeZgKJqiWub<P%Y#(0zlY`@tb+aeT|IV_2geTB??fbhZZWjh+Kt
z&mMeRXQR<XO3(KV7iI01c+fP=fvdx|2AYF7Feg+S9Kj{i=m@7wW?pJEhibBBw^%wn
zzFbc|K3{arSU9;P{_`oMqi)Jn!+=Vd=^v}A&jYzX;CQi_*=Vi%cMW%oY5U|796Oi*
zy#x-Y{hqci{?DZyjdneV{jrp<OicbD%vGmV#Q^P%?ECb*hYDcNfENXV)}Y8pX#zq*
zd5mvzm`wOG`9-Fnp%#{wM$pV;lXI^S?E}Y2_Kw~lzJC{a+_{cZmo^!UB%FBRbbuoT
z&Q|O9`$tZF7a~))Q1S3A5~vMX@HD#g(ea=%GBab-@ltXr)W=PPSu%Ls{6X}~(zKkX
zfT5_U_=#4PWa`p>f0RkT*VUl%hyKit$apq?l>j6P4vIK9%3-!xj?4Iyv0S~zf6M!o
zRSkHPfdnh>!DJ=@w>LpH37@)+=VR=t4=7JlaZ}BlG(iiETJv{=BvV#uJW1VxN1J)d
z>-EJGmqQO2ft83P;!eY5?wk+<-rO1k1BGeG&?zrrdEVErNe72^50nDO>sh$!FS`9j
z;D0*(Y<#Bkr2;sc+uG_3hwh%ew^|(jGM^^=&fs)NE6R2Y-p)p9;<Ucl^jhw;gprMo
z_I&R{o-co_pXiC~?iN5IUiI<Gqa~5fyhH2@M%o5Lo9F)J8Uc@ExUg~soPJs9^5OUM
z^P8{G!uE|NV4O3<NcZ+wsWrau@Jyz842pq4{tFIYDTCQ2hVR%^iHqD+EUWlOYGAYF
z%j1%6=zxDwI)2Gt7TIjRfB^$9isRR>lmPn=R~ZOC@{Nli`bOKW@1UJqu62U9v9XCH
z;!W1+@YuW^>yI+kX+Ojs^m%2?vN=b1y;0I}+sE8NN2}H>KXhF635Mm*!5*iVN@3I!
z@R23pmmR6L>m=g$yE{84ifq?EtD^SKbII0GE>n#HXD|V~^ZBDw$>Jsce^)CthU6ch
z5%lH?qc}LZuWtik9o_G>Gcq%*B#8+y`mc<~<S`I+bh2JR(AB=$NeH$D^hW3-F6~@Y
z3<2cYnuDWvGIEF&)PvqiaTkNdQ_l9s!4m)hmn(9!!()5<+(t>Wf^7{`x6OtYs|+e(
zU>qCVP-3rqy;e*R^4nqIAVfO!Te&{^hl)VRgaeMS6iR1FF4<^XVJ~Jhc~o#Y0n2SJ
z^qHGykqZVU3#|<Ri{;|WxmVira5!eyY_7<iEfNk#toQ2^xLFl)p8n=6p<^hs+=B!H
z8#*Bj)Pv|~Xt{#`9Dc+K0twhu-Eyv!RmM>L47SgjAUC@gCT@e}G|Z-)L4LeiZ#~vr
zHHb<;U{vRU_~&RJN}$8tNkUSxdt@dqF%ct@a~DsV4E>vA@P46#og;<g7jPb<(6Z?~
zl7JHu#G&c4>o}R}{cHHXcnf8W?l&o(tnM^hlfSaiQObq8-n@!c8zhM!>O%|UPh_pE
z2r4w2Oy-Lf0z-mURJUkWcA?gPXxqSYY@z_RnvGUrAw}fLT9Dt74XPJ?j+S^69Uw-7
zgCcZhB#UG-jjs}I?GGT=!w1rMp`RZvcbUxop_t#TUqcQz|3rr~&5d868X2L4lD(hQ
zvW5LjxatzSo$d97lClJ}Y~Zx)(UOnve5r;MpmG093~DE3<wRh%#Q{5&!`%M-5^S!F
zZTE%jAJ!PgCnsllc+TVwTy4X2<Qth4o6U@NdcnZi0-g|O|Jk~op5Hs?r&OQ-q-QpH
zvs*f{xb}Hb;5(gBTG!s_Uuz5fHE!a>H2qqhNUPPDI6VC6^5$P6o*ci!61a}#s4y^M
zu*mQ!;d07}8g+k{lVrf?ObiYE1WTo<{PGep8U&Ah-Qm62?v}g6E#6YQpKmY_?#zyR
z*m1v^G8`)Y)5Rfy%P9|Rl#DQRxZj~6;)O*<#vaS5q<j^NUXG$285uz%B&3atL)|&v
zp_)kRumgt!xSY^Bbm&nrzvjDLW0NwE>7_valc$5HBf*Ip{L!SLfB~kXE2jWjEO?VT
zPWC9(GEgO94m)*j-)&SC)Y^8&^ym$Hu|<h~FPb~x&Ka>{0}DpAX5CQQRyBFomTT<3
zAyZm)IIHPous=9-=|X8AF%WMZ^C=XBcd_`$HLS=NVw^8)ZUH^M0Nytb9Rcq<pyl>@
zu;bRfV`BmqCC<o6_rIolijjygO|j(%urV90?$iy{tuz4-9*$0YM+8{QZ}`&eiaEgn
PdO$)%R=847&;Ne_sH_`5
literal 0
HcmV?d00001
diff --git a/docs/images/usgs-icon.png b/docs/images/usgs-icon.png
new file mode 100644
index 0000000000000000000000000000000000000000..034fdba1d046f4da94dc04fb034f6f5b55a76c49
GIT binary patch
literal 1098
zcmV-Q1hxB#P)<h;3K|Lk000e1NJLTq000>P000>X0ssI2ON$aT0000PbVXQnQ*UN;
zcVTj606}DLVr3vnZDD6+Qe|Oed2z{QJOBU#>`6pHRCwBAl&nvD{^>mfH2@P2I|o$^
zlHwC$p^8DqGRlji3n(><n~kH|H6-8Ghl`D!<?GL%<U2=JWkyJbiL5e^ef+@<#<drZ
zfByOX_N(V>FCV+{`WZ;c|NjI{VPRr!@`@^R2w-Mn`ugi<$>v21PVQ#>57YVU@1OlQ
zFE(vicI@Rn2E3*@sOYqL$5_g%1KI0O9d0|Z?aYJg%uLLTvySarbLsf)*Uxx3IQ><P
zTvYWYpWe0h(s8V=<7MZ}w()B5i~>66<F~I9cdo5JvL0x$FgI_#djz9Eb@YetU)4lq
z9aXh}N<V!6=A~|U_38cEJ*&}-14h=O=zJ}4Ss?r1-K*JaW?g;#nBm`lFHPfV!D;eB
zVvHWs>cjP|;w)X67#SgYfJO^&a-V&CXU&!4C+^?+_Uk85zmuA7n7%bT3+tyJ-<o!<
znsj)}@4tVAxOh5z;}T7sfWi0l<6Fk>zkYJCvH^|QbL-;z%O@|tywAeKY9*x>VQix#
zt?={DZ=im-(+=IZRJLQu$w#+=Y&Q*qi2*4ZV$wkNrYomPH!lQ*{j*Q+vewMpc;ysC
zgT1o0B%jdtKR>;d3{<3L7o9yQ!o~CD*N;PYu3mff1n6;Y7WQc&nQ><JK*evre$HJ#
zYx%h&pvawhY<JJ0^><!92XYGRd~<BQl!YZAhQ9dxL4sF6f`fO?sof_Y-um|Yr=yaN
ztCpd^nvs^YJW#>1^M~uVFTe8!q_^BDkWsuY;pLYP22zT^X!g`F0*an|cx(5qix-~W
z|M&mDhNzUSteU63IV9;Y!ou|O^M}A7n{#3hkgY2zU*j4YW?;?2!O9wMU^gQ&n}dZ7
zsCnX{&1IVx{rUG79!Bj<jFFe^ax6V|-nqcd#?JVk@$Az(t1cV^o6V47?%Ly*z|X-2
z;$405R7+e6$U61tcHxG3#~$3knm*0s)%tuB58t`6?DDbuZ=Or=3pq%sCfd4LDQW>_
zufKd!ylFlt?0@|EJ>%HU+U-lf{QQA4u`@Cnh{){8Z4u_-0|p!yD?3COm|_;3-dD42
z+57KbfbM#fvu@V@+gAu@WkyB~5y{E^Dc9dV=U`<K<l?>c>e<56`)+}Av5Bk-qgF@m
zwU>{HEg2XY6on*!dFbVrkF$^Oy#Der3lod6ta6IEdxW7Cqf$%yy|*t(Dr$JxIeYz+
zeKZX@+1P<W1Wf%9ab^)0vv=RVkYpCHMA>rn<hskp|1mHLbMpX0`O@<TlMZcRRBg+=
z{rWk%r6Dk3FtRbT08IyGXC}&uXhw)LA;l3B1N8vY=O5pxV$jDQ-v9y(0E}R-_$hP-
Q!2kdN07*qoM6N<$f{6q+&j0`b
literal 0
HcmV?d00001
--
GitLab