From f904ecba042e9b8e3838fc6ee5d9b2eb76de2f1f Mon Sep 17 00:00:00 2001
From: Brandon Clayton <bclayton@usgs.gov>
Date: Tue, 17 Jan 2023 09:02:39 -0700
Subject: [PATCH] Add docs from GitHub wiki
---
README.md | 8 +-
docs/Building-&-Running.md | 145 +++++++++++
docs/Configuration.md | 127 ++++++++++
docs/Dependencies-&-Development.md | 18 ++
docs/Developer-Basics.md | 47 ++++
docs/Functional-PSHA.md | 108 ++++++++
docs/Ground-Motion-Models.md | 23 ++
docs/Model-Changes.md | 3 +
docs/README.md | 25 ++
docs/Sites.md | 73 ++++++
docs/Source-Models.md | 103 ++++++++
docs/Source-Types.md | 385 +++++++++++++++++++++++++++++
docs/USGS-Models.md | 11 +
docs/What-is-Epsilon?.md | 7 +
docs/_Footer.md | 1 +
docs/_Sidebar.md | 13 +
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
20 files changed, 1092 insertions(+), 5 deletions(-)
create mode 100644 docs/Building-&-Running.md
create mode 100644 docs/Configuration.md
create mode 100644 docs/Dependencies-&-Development.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/Model-Changes.md
create mode 100644 docs/README.md
create mode 100644 docs/Sites.md
create mode 100644 docs/Source-Models.md
create mode 100644 docs/Source-Types.md
create mode 100644 docs/USGS-Models.md
create mode 100644 docs/What-is-Epsilon?.md
create mode 100644 docs/_Footer.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/README.md b/README.md
index 5e1ea4239..1d1aa08b5 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,5 @@
-# nshmp-haz
+# Legacy nshmp-haz
+
[](https://travis-ci.com/usgs/nshmp-haz)
[](https://codecov.io/gh/usgs/nshmp-haz)
[](https://www.codacy.com/app/pmpowers/nshmp-haz?utm_source=github.com&utm_medium=referral&utm_content=usgs/nshmp-haz&utm_campaign=Badge_Grade)
@@ -8,7 +9,4 @@ Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/)) code for perform
probabilistic seismic hazard (PSHA) and related analyses. These codes are intended for
use with seismic hazard models developed by the NSHMP for the U.S. and its territories.
-Please see the [wiki](https://github.com/usgs/nshmp-haz/wiki/) for more information.
-
-> This repository has been moved to GitLab:
-> [https://code.usgs.gov/ghsc/nshmp/nshmp-haz](https://code.usgs.gov/ghsc/nshmp/nshmp-haz).
+Please see the [docs](./docs/README.md) for more information.
diff --git a/docs/Building-&-Running.md b/docs/Building-&-Running.md
new file mode 100644
index 000000000..d8589a26f
--- /dev/null
+++ b/docs/Building-&-Running.md
@@ -0,0 +1,145 @@
+<!-- Overview -->
+### Overview
+* [Build and Run Locally](#build-and-run-locally)
+* [Run with Docker](#run-with-docker)
+
+<!-- Build and Run Locally -->
+## Build and Run Locally
+
+### Build Requirments
+Building and running *nshmp-haz* requires prior installation of Git and Java.
+Please see [this page](developer-basics) 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://github.com/usgs/nshmp-haz.git
+cd nshmp-haz
+./gradlew assemble
+```
+
+This creates a single file, `build/libs/nshmp-haz.jar`, with no dependencies for use in 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, Gradle itself included.
+
+### Computing Hazard
+The [`HazardCalc`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/HazardCalc.html) program computes hazard curves at one or more sites for a variety of intensity measures. Computing hazard curves requires at least 2, and at most 3, arguments. For example:
+
+```bash
+java -cp nshmp-haz.jar gov.usgs.earthquake.nshmp.HazardCalc model sites [config]
+```
+
+At a minimum, the [source model](Source-Models) and the [site(s)](Sites) at which to perform calculations must be specified. The source model should be specified as a path to a directory or zip file. 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. Under the 2-argument scenario, model initialization and calculation configuration settings are drawn from the [configuration](configuration) file that *must* reside at the root of the model directory. Alternatively, the path to a custom configuration file may also be supplied as a third argument. It can be used to override any calculation settings, but not model initialization settings.
+
+See the [examples](/usgs/nshmp-haz/tree/master/etc/examples) directory for more details.
+
+### Computing Deaggregations
+Like `HazardCalc`, The [`DeaggCalc`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/DeaggCalc.html) program performs deaggregations 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.DeaggCalc model sites returnPeriod [config]
+```
+
+Deaggregations build on and output `HazardCalc` results along with other deaggregation specific files. Deaggregations also have some independent [configuration](configuration#config-deagg) options.
+
+### Computing Earthquake Rates and Probabilities
+
+*TODO*
+
+### Matlab Access
+Another convenient way to use the nshmp-haz library is via Matlab. A [sample script](/usgs/nshmp-haz/blob/master/etc/matlab/) contains the necessary instructions.
+
+
+<!-- Run with Docker -->
+## Run with Docker
+
+### Build Requirments
+- [Docker](https://docs.docker.com/install/)
+
+### Getting Latest Docker Image
+To ensure you are on the latest nshmp-haz update, pull the image from Docker:
+
+```bash
+docker pull usgs/nshmp-haz-legacy
+```
+
+### 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-legacy>
+which can be run with:
+
+```bash
+docker run \
+ -e PROGRAM=<deagg | hazard | rate> \
+ -e MODEL=<WUS-20[08|14|18] | CEUS-20[08|14|18] | AK-2007> \
+ -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-legacy
+
+# Example
+docker run \
+ -e PROGRAM=hazard \
+ -e MODEL=WUS-2018 \
+ -v $(pwd)/sites.geojson:/app/sites.geojson \
+ -v $(pwd)/config.json:/app/config.json \
+ -v $(pwd)/hazout:/app/output \
+ usgs/nshmp-haz-legacy
+```
+
+Where:
+
+* `PROGRAM` is the nshmp-haz program to run:
+ * deagg = [`DeaggCalc`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/DeaggCalc.html)
+ * hazard = [`HazardCalc`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/HazardCalc.html)
+ * rate = [`RateCalc`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/RateCalc.html)
+
+* `MODEL` is the [USGS model](https://github.com/usgs/nshmp-haz/wiki/usgs-models) to run with:
+ * CEUS-2018 or WUS-2018: [Conterminous U.S. 2018](https://github.com/usgs/nshm-cous-2018)
+ * CEUS-2014 or WUS-2014: [Conterminous U.S. 2014](https://github.com/usgs/nshm-cous-2014)
+ * CEUS-2008 or WUS-2008: [Conterminous U.S. 2008](https://github.com/usgs/nshm-cous-2008)
+ * AK-2007: [Alaska 2007](https://github.com/usgs/nshm-ak-2007)
+
+* `RETURN_PERIOD`, in years, is only required when running a deaggregation
+
+* The [site(s)](Sites) file must be a GeoJSON or CSV file and the absolute path to the site(s) file
+must be given
+ * CSV example: `$(pwd)/my-csv-sites.csv:/app/sites.csv`
+ * GeoJSON example: `$(pwd)/my-geojson-sites.geojson:/app/sites.geojson`
+
+* The absolute path to the [configuration](configuration) must be given but is an optional argument
+ * Example: `$(pwd)/my-custom-config.json:/app/config.json`
+
+* To obtain any results from the Docker container the absolute path to an output directory
+must be given
+ * Example: `$(pwd)/my-hazard-output:/app/output`
+
+
+#### Running 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-legacy
+```
+
+Where:
+
+* `JAVA_XMS` is the intial memory for the JVM
+ * Default: 8g
+
+* `JAVA_XMX` is the maximum memory for the JVM
+ * Default: 8g
+
+### Next: [Configuration](configuration)
diff --git a/docs/Configuration.md b/docs/Configuration.md
new file mode 100644
index 000000000..737b1b9c9
--- /dev/null
+++ b/docs/Configuration.md
@@ -0,0 +1,127 @@
+A `config.json` file resides at the root of every [source model](source-models).
+
+This file supplies model initialization and default calculation configuration parameters; see the [examples](/usgs/nshmp-haz/tree/master/etc/examples) directory, or any [USGS model](usgs-models), for examples.
+
+The file must be composed of well-formed [JSON](http://json.org). [Why JSON?](#why-use-json)
+
+### 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)
+
+### Calculation Configuration Parameters
+
+Calculation configuration parameters are optional (i.e. defaults are used for missing values) and overridable. Please see [building and running](building-&-running) and the [examples](/usgs/nshmp-haz/tree/master/etc/examples) for details on how to override a calculation configuration.
+
+Parameter | Type | Default | Notes |
+--------- | ---- | ------- | ----- |
+<a id="config-hazard"></a>__`hazard`__ |
+ `.exceedanceModel` |`String` | `TRUNCATION_UPPER_ONLY` |[`ExceedanceModel`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/ExceedanceModel.html)
+ `.truncationLevel` |`Double` | `3.0`
+ `.imts` |`String[]` | `[ PGA, SAOP2, SA1P0 ]` |[`Imt`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/gmm/Imt.html)
+ `.defaultImls` |`Double[]` | PGA, SA = `[ 0.0025, 0.0045, 0.0075, 0.0113, 0.0169, 0.0253, 0.0380, 0.0570, 0.0854, 0.128, 0.192, 0.288, 0.432, 0.649, 0.973, 1.46, 2.19, 3.28, 4.92, 7.38 ]`<br/><br/>PGV = `[ 0.0100, 0.0177, 0.0312, 0.0552, 0.0976, 0.173, 0.305, 0.539, 0.953, 1.68, 2.98, 5.26, 9.30, 16.4, 29.1, 51.3, 90.8, 160, 284, 501 ]`
+ `.customImls` |`Map<String, Double[]>` | *empty* |[example](/usgs/nshmp-haz/blob/master/etc/examples/2-custom-config/config.json)
+ `.gmmUncertainty` |`Boolean` | `false` |[:one:](#one-hazardgmmuncertainty)
+ `.valueFormat` |`String` | `ANNUAL_RATE` |[`ValueFormat`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/ValueFormat.html)
+<a id="config-deagg"></a>__`deagg`__ | | |[:two:](#two-deagg)
+ `.bins` |`Object` |
+ `.contributorLimit` |`Double` | `0.1`
+<a id="config-rate"></a>__`rate`__ |
+ `.bins` |`Object` | |[:three:](#three-ratebins)
+ `.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` | |[`ValueFormat`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/ValueFormat.html)
+<a id="config-site"></a>__`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` or `NaN` |[:four:](#four-sitez1p0-sitez2p5)
+ `.z2p5` |`Double` | `null` or `NaN` |[:four:](#four-sitez1p0-sitez2p5)
+<a id="config-output"></a>__`output`__ |
+ `.directory` |`String` | `hazout`
+ `.dataTypes` |`String[]` | `[ TOTAL ]` |[`DataType`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/DataType.html)
+<a id="config-performance"></a>__`performance`__ |
+ `.optimizeGrids` |`Boolean` | `true` |[:six:](#six-performanceoptimizegrids)
+ `.collapseMfds` |`Boolean` | `true` |[:seven:](#seven-performancecollapsemfds)
+ `.systemPartition` |`Integer` | `1000` |[:eight:](#eight-performancesystempartition)
+ `.threadCount` |`String` | `ALL` |[`ThreadCount`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/ThreadCount.html)
+
+###### :one: `hazard.gmmUncertainty`
+
+If values for additional epistemic uncertainty on ground motion have been defined, this value en/disables this feature.
+
+###### :two: `deagg`
+
+The `deagg.bins` field is mapped to a data container that specifies the following default ranges and intervals for distance, magnitude, and epsilon binning:
+
+``` JSON
+"bins": {
+ "rMin": 0.0,
+ "rMax": 200.0,
+ "Δr": 10.0,
+ "mMin": 5.0,
+ "mMax": 8.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.
+
+`contributorLimit` specifies the cutoff (in %) below which contributing sources are not listed in deaggregation results.
+
+###### :three: `rate.bins`
+
+The `rate.bins` field is mapped to a data container that specifies the following default magnitude binning range and interval:
+
+``` JSON
+"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.
+
+###### :four: `site.z1p0`, `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.
+
+###### :five: `output.flushLimit`
+
+The number of results to write at a time. More memory is required for higher limits.
+
+###### :six: `performance.optimizeGrids`
+
+Grid 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.
+
+###### :seven: `performance.collapseMfds`
+
+Some magnitude-frequency distribution logic-trees can be combined. This is currently always `true`.
+
+###### :eight: `performance.systemPartition`
+
+The number of ruptures in a fault-system source to process concurrently.
+
+
+### Why Use JSON?
+Whereas sources are defined using XML, configuration files use JSON. Although one or the other formats could be used exclusively, each has unique characteristics and benefits. For instance, for long files, XML is somewhat more readable than JSON. It also permits comments inline, whereas JSON does not. Java has a built in support for writing highly performant XML parsers, and as there is not a 1:1 relationship between source model XML and resultant Java objects in *nshmp-haz*, it is a bit easier to work with. XML also permits a formal structure to be imposed, and although XML schema are not presently used, they may be in the future.
+
+JSON, on the other hand, is a very simple data exchange format designed with the web in mind. The values that govern calculation settings are most likely to be exposed via web services and the job of exchanging such data is much more straightforward using a format that maps natively to Javascript objects.
+
+### Next: [Site Specification](sites)
+
+
+
diff --git a/docs/Dependencies-&-Development.md b/docs/Dependencies-&-Development.md
new file mode 100644
index 000000000..9014ece23
--- /dev/null
+++ b/docs/Dependencies-&-Development.md
@@ -0,0 +1,18 @@
+This project loosely adheres to [Google Java Style](https://google.github.io/styleguide/javaguide.html) and is informed by [Effective Java](http://en.wikipedia.org/wiki/Joshua_Bloch#Effective_Java). All source files and documentation are encoded using [UTF-8](https://en.wikipedia.org/?title=UTF-8). Developers should also consider the following:
+
+* Line lengths:
+ * code: __100__, but shorter is better.
+ * comments: __80__, for readability.
+* Use unicode symbols where possible: `double μ = 0.4;`
+* Use static imports for only the most common utilities and preconditions:
+ * `java.lang.math`
+ * `com.google.common.base.Preconditions`
+
+### Dependencies
+
+The following are required to build and run *nshmp-haz*. Additional testing a code coverage dependencies are listed in the [license](/usgs/nshmp-haz/blob/master/LICENSE.md).
+
+1. [Java 8 JDK](http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html) (or higher)
+2. [Ant](http://ant.apache.org)
+3. [Guava](http://code.google.com/p/guava-libraries/)
+4. [Gson](https://code.google.com/p/google-gson/)
diff --git a/docs/Developer-Basics.md b/docs/Developer-Basics.md
new file mode 100644
index 000000000..9b8a6f6a0
--- /dev/null
+++ b/docs/Developer-Basics.md
@@ -0,0 +1,47 @@
+The following provides basic guidance on how to set up command-line use of nshmp-haz.
+
+### What are Git and GitHub?
+
+* __Git__ is a distributed version control system ([more](https://git-scm.com)).
+* __GitHub__ is a public hosting service that facilitates sharing and collaborative development of code and provides a home on the web for documentation and other project resources ([more](https://help.github.com/categories/bootcamp/)).
+* Git repositories may be created anywhere on your system. Git repositories may be created locally and pushed to Github for sharing, or they may be created on GitHub and pulled down to your local system for editing.
+
+### Required Software
+
+* Java 8 JDK: [Oracle](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) or [OpenJDK](http://openjdk.java.net/install/)
+* [Git](https://git-scm.com/downloads)
+ - 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 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 1.8)"
+# Linux
+export JAVA_HOME=/usr/lib/jvm/jdk1.8.0_144
+```
+
+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\jdk1.8.0_144
+```
+
+### Set Up Git
+
+Follow the instructions on [GitHub](https://help.github.com/articles/set-up-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), respectively. This installs the components your system requires along with a helpful desktop application for managing communication between local repositories and GitHub, and viewing file diffs as you make changes. Launch the application and perform any configuration steps, using your GitHub username and email address.
+
+### Get the Code
+```bash
+cd /directory/for/code
+git clone https://github.com/usgs/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:
+* Eclipse IDE for [Java Developers](http://www.eclipse.org/downloads/packages/eclipse-ide-java-developers/oxygenr) or [Java EE Developers](http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/oxygenr), if you plan on developing web services.
+* `File > Import > Gradle > Existing Gradle Project`
+
+### Return to: [Building & Running](building-&-running)
diff --git a/docs/Functional-PSHA.md b/docs/Functional-PSHA.md
new file mode 100644
index 000000000..44675fa82
--- /dev/null
+++ b/docs/Functional-PSHA.md
@@ -0,0 +1,108 @@
+### 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):
+
+[[images/psha-formula.png|alt=PSHA formulation of 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:
+
+[[images/psha-linear.png|alt=PSHA linear pipeline]]
+
+The functional pipeline can be processed stepwise:
+
+[[images/psha-functional.png|alt=PSHA functional pipeline]]
+
+**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..c600f8858
--- /dev/null
+++ b/docs/Ground-Motion-Models.md
@@ -0,0 +1,23 @@
+Ground motion models (GMMs) forecast the range of ground motions that may be observed conditioned on the occurrence of various earthquakes. Internally, every earthquake in a `HazardModel` is parameterized as a `GMM_Input`, for which ground motions can be calculated.
+
+### Ground Motion Model File Structure
+
+```XML
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<GroundMotionModels>
+ <ModelSet maxDistance="150.0">
+ <Model id="BA_08" weight="0.3333"/>
+ <Model id="CB_08" weight="0.3333"/>
+ <Model id="CY_08" weight="0.3334"/>
+ </ModelSet>
+</GroundMotionModels>
+```
+Ground motion model files also provide limited support for additional epistemic uncertainty on ground motion ([example](https://github.com/usgs/nshmp-model-cous-2008/blob/master/Western%20US/Fault/gmm.xml)) and will likley support uncertainty on ground motion sigma with the anticipated implementation of [NGA-East](http://peer.berkeley.edu/ngaeast/). The format for these uncertainty models is subject to change at any point in the future.
+
+A second distance cutoff is also supported ([example](https://github.com/usgs/nshmp-model-cous-2014/blob/master/Central%20%26%20Eastern%20US/Fault/gmm.xml)). The models specified at the greater distance must be a subset of the near-distance models, but may have different weights. This feature may be removed in future updates.
+
+The weights in any set of ground motion models need not sum to 1.0, but this may be enforced in the future.
+
+### Next: [USGS Models](usgs-models)
+
+
diff --git a/docs/Model-Changes.md b/docs/Model-Changes.md
new file mode 100644
index 000000000..0ac26320d
--- /dev/null
+++ b/docs/Model-Changes.md
@@ -0,0 +1,3 @@
+This page documents known implementation differences between nshmp-haz, USGS Fortran codes, and OpenSHA.
+
+* __NGA Focal Mechanism Flags:__ Whereas BA 2008 and other models accepted double values for focal mechanism weights (f_s, f_r, f_n, f_u), their intended use was for only 1 to be set to 1 and the rest to 0. The 2008 fortran codes supplied fractions (e.g. f_s=0.5 and f_r=0.5). The current code treated each focal mechanism type independently and then added the weighted hazard curves. This was corrected in 2014 nshm fortran code, but nshmp-haz behavior remains inconsistent with 2008 Fortran behavior.
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..4d5264563
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,25 @@
+***nshmp-haz*** is a Java-based platform for conducting probabilistic seismic hazard (PSHA) and related analyses. It is developed and maintained by the National Seismic Hazard Mapping Project ([NSHMP](http://earthquake.usgs.gov/hazards/)) within the U.S. Geological Survey's ([USGS](https://www.usgs.gov)) earthquake hazards program ([EHP](http://earthquake.usgs.gov)). The primary goals *nshmp-haz* are to:
+
+1. Enable high performance seismic hazard calculations required to generate detailed maps over large areas and
+2. Support a variety of USGS web services and applications related to seismic hazards research and the dissemination of hazard data.
+
+### Overview
+* [Building & Running](building-&-running)
+ * [Configuration](configuration)
+ * [Site Specification](sites)
+* [Source Models](source-models)
+ * [Source Types](source-types)
+ * [Ground Motion Models](ground-motion-models)
+ * [USGS Models](usgs-models)
+* [Examples](https://github.com/usgs/nshmp-haz/tree/master/etc/examples)
+* [Dependencies & Development](dependencies-&-development)
+* [Functional PSHA](functional-psha)
+* [API Docs](http://usgs.github.io/nshmp-haz/javadoc)
+* [License](https://github.com/usgs/nshmp-haz/blob/master/LICENSE.md)
+
+For more information on PSHA see:
+
+* [Probabilistic Seismic Hazard Analysis, a Primer](http://www.opensha.org/sites/opensha.org/files/PSHA_Primer_v2_0.pdf) by Edward Field
+* [An Introduction to Probabilistic Seismic Hazard Analysis](http://web.stanford.edu/~bakerjw/Publications/Baker_(2015)_Intro_to_PSHA.pdf) by Jack Baker
+
+### Next: [Building & Running](building-&-running)
diff --git a/docs/Sites.md b/docs/Sites.md
new file mode 100644
index 000000000..b9f47db2c
--- /dev/null
+++ b/docs/Sites.md
@@ -0,0 +1,73 @@
+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
+
+In the simple case where there is 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 defaults configuration](configuration#calculation-configuration-parameters)):
+
+```
+ name: Unnamed
+ vs30: 760.0
+ vsInf: true
+ z1p0: NaN (GMM will use default basin depth model)
+ z2p5: NaN (GMM will use default basin depth model)
+```
+
+
+### 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. Moreover, GeoJSON files are rendered directly on GitHub providing immediate visual feedback as to the contents of a file. See the [GitHub GeoJSON](https://help.github.com/articles/mapping-geojson-files-on-github/) page for more information.
+
+*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 `Point` `FeatureCollection`. 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 on GitHub and elsewhere.
+
+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. This polygon is used primarily when outputting hazard curves in the USGS binary format. 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.
+
+### Next: [Source Models](source-models)
diff --git a/docs/Source-Models.md b/docs/Source-Models.md
new file mode 100644
index 000000000..a091f89a9
--- /dev/null
+++ b/docs/Source-Models.md
@@ -0,0 +1,103 @@
+Sources are representations of earthquakes that occur with some rate. They can be well defined faults with a specific geometry, or point sources derived from historic earthquake catalogs for which planar pseudo-fault representations may be used. In either case, there may be multiple earthquake sizes associated with a given source.
+
+### Outline
+
+* [Source File Structure](#source-file-structure)
+ - [Sample File Structure](#sample-file-structure)
+* [Common Source Elements](#common-source-elements)
+ - [Magnitude-Frequency Distributions (MFDs)](#magnitude-frequency-distributions-mfds)
+ - [Rupture-Scaling Relations](#rupture-scaling-relations)
+
+### Source File Structure
+
+An earthquake source model, or [HazardModel](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/eq/model/HazardModel.html), is specified using XML files grouped in folders by [SourceType](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/eq/model/SourceType.html). The currently supported source types are:
+
+```
+[ Area, Cluster, Fault, Grid, Interface, Slab, System ]
+```
+
+One level of nested folders is permitted to facilitate logical 'source groups' and the use of different ground motion models ([GMMs](ground-motion-models) or [model initialization](configuration) settings. Source files, except those for [Fault System Sources](source-types#system-sources), and nested 'source group' folders may be given any name. Ground motions are computed using the models defined in the `gmm.xml` file in each source directory. If a 'source group' does not contain `gmm.xml`, one is required in the parent 'source type' folder. See file structure example below.
+
+#### Sample File Structure:
+
+```
+ModelDirectory/
+ ├─ config.json
+ ├─ Fault/ <─── source type
+ │ ├─ faultSources1.xml
+ │ ├─ faultSources2.xml
+ │ ├─ ...
+ │ ├─ gmm.xml
+ │ │
+ │ └─ FaultGroup/ <─── source group
+ │ ├─ otherFaultSources.xml
+ │ └─ gmm.xml
+ │
+ ├─ Grid/
+ │ ├─ gridSources.xml
+ │ ├─ ...
+ │ ├─ gmm.xml <─── uses parent GMMs ─â”
+ │ │ │
+ │ ├─ GridGroup1/ │
+ │ │ └─ otherGridSources.xml ──────────┘
+ │ │
+ │ └─ GridGroup2/
+ │ ├─ otherGridSources.xml
+ │ └─ gmm.xml
+ └─ ...
+```
+
+### Common Source Elements
+
+#### Magnitude-Frequency Distributions (MFDs)
+ A source requires a description of the sizes and rates of all earthquakes it is capable of generating, otherwise known as a magnitude-frequency distribution. For conciseness, all source files may supply default MFDs so that individual sources need only specify those attributes that are different from the default. Standard [MFD types](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/mfd/MfdType.html):
+
+ * Single
+ * [Gutenberg-Richter](http://en.wikipedia.org/wiki/Gutenberg–Richter_law)
+ * [Tapered Gutenberg-Richter](http://scec.ess.ucla.edu/~ykagan/moms_index.html)
+ * Incremental
+
+XML examples:
+```XML
+<!-- Single magnitude MFD
+ - Used to represent the rupture of a specific size event
+ on a fault; historically this may have been referred to
+ as a 'characteristic' rupture.
+ - Can float over or fill source. -->
+<IncrementalMfd type="SINGLE" weight="0.25" id="NAME"
+ rate="1.0" floats="[true | false]" m="6.5" />
+
+<!-- Gutenberg-Richter MFD
+ - Used to represent a range of evenly discretized magnitude
+ events with systematically varying rates.
+ - Always floats when used for a fault source; never floats
+ for grid sources.
+ - 'a' is the incremental log10(number of M=0 events). -->
+<IncrementalMfd type="GR" weight="0.25" id="NAME"
+ a="1.0" b="1.0" dMag="0.1" mMin="5.0" mMax="7.0" />
+
+<!-- Tapered Gutenberg-Richter MFD
+ - Same as Gutenberg-Richter, above, but with an exponential
+ taper applied to the cumulative number of events with
+ seismic moment greater than M.
+ - Only used for grid sources. -->
+<IncrementalMfd type="GR_TAPER" weight="0.25" id="NAME"
+ a="1.0" b="1.0" dMag="0.1" mCut="6.5" mMin="5.0" mMax="7.0" />
+
+<!-- Incremental MFD
+ - General purpose MFD that consists of varying magnitudes
+ and rates.
+ - Can float over or fill source. -->
+<IncrementalMfd type="INCR" weight="0.25" id="NAME"
+ mags="[5.05, 5.15, ...]" rates="[1.0e-2, 0.9e-2, ...]"
+ floats="[true | false]" />
+```
+
+#### Rupture Scaling Relations
+
+Fault-based sources commonly require a model that describes the geometry of partial (or floating) ruptures. Likewise, grid sources require a model of fault-length or -area when building pseudo-faults or performing point source distance corrections that consider magnitude-dependent rupture sizes with unkown strike. Such models are composed of published magnitude-length or -area relations and restrictions on aspect-ratio and/or maximum rupture width that are independent of the published model.
+
+See the [API Docs](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/eq/fault/surface/RuptureScaling.html) for details on specific model combinations and implementations. A rupture scaling model is always sepcified as an attribute of `<SourceProperties />`; see examples in next section.
+
+### Next: [Source Types](source-types)
+
diff --git a/docs/Source-Types.md b/docs/Source-Types.md
new file mode 100644
index 000000000..39631fd32
--- /dev/null
+++ b/docs/Source-Types.md
@@ -0,0 +1,385 @@
+There are seven basic [source types](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/eq/model/SourceType.html):
+```
+[ Area, Cluster, Fault, Grid, Interface, Slab, System ]
+```
+Source files for each are written in [plain old XML](http://en.wikipedia.org/wiki/Plain_Old_XML). All attributes present in the examples below are required with the exception of MFD's for which default distributions are being used; see examples below.
+
+__Note on value types:__ Most attribute values or element content are parsed as a `String`, `Double`, `Double[]` (array) or `Boolean`; those attribute values in ALL_CAPS are parsed as `enum` types and are case sensitive, [for example](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/mfd/MfdType.html).
+
+__Note on using default MFDs:__ Default MFDs, if supported and present, must be fully specified. Any MFD encountered in a source will map all missing attributes from the default(s) of the same `type`. If no default for an MFD `type` is present, the source MFD must be fully specified
+
+__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 claculations, always use positive or negative longitudes exclusively.
+
+### 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)
+
+### Area Sources
+
+Area sources are similar to [Grid Sources](#grid-sources) except that a single MFD applies to an entire area with rates proportionally scaled for use at all grid nodes. The discretization of area sources into grids may be allowed to [vary with distance](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/eq/model/AreaSource.GridScaling.html) from a site as specified by a model initialization [configuration](configuration).
+
+```XML
+<?xml version="1.0" encoding="UTF-8"?>
+<AreaSourceSet name="Source Set Name" weight="1.0">
+
+ <!-- Sources ... -->
+ <Source name="Area Source Name" id="0">
+
+ <!-- Specify MFDs ... -->
+ <IncrementalMfd type="GR" weight="1.0" id="name"
+ a="0.0" b="0.8" dMag="0.1" mMax="7.0" mMin="5.0" />
+
+ <Geometry>
+
+ <!-- Border polygon. Individual locations specified by
+ whitespace separated tuples of longitude,latitude,depth
+ (NO SPACES); same as the KML <coordintes/> format. -->
+ <Border>
+ -117.0,34.0,0.0
+ -117.1,34.1,0.0
+ -117.3,34.2,0.0
+ ...
+ </Border>
+ </Geometry>
+ </Source>
+
+ <!-- Add more sources ... -->
+ <Source />
+ ...
+
+</AreaSourceSet>
+```
+
+### 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.
+
+```XML
+<?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>
+```
+
+### Fault Sources
+
+```XML
+<?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
+
+```XML
+<?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>
+```
+
+### Interface Sources
+
+```XML
+<?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>
+```
+
+### Slab Sources
+
+Subduction intraslab sources are currently specified the same way as [Grid Sources](#grid-sources).
+
+
+### 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
+<?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
+<?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>
+```
+
+`grid_sources.xml` is structured and processed in the same way as a [grid source](#grid-sources).
+
+### Next: [Ground Motion Models](ground-motion-models)
+
diff --git a/docs/USGS-Models.md b/docs/USGS-Models.md
new file mode 100644
index 000000000..270190643
--- /dev/null
+++ b/docs/USGS-Models.md
@@ -0,0 +1,11 @@
+The USGS has historically updated the earthquake hazard model for the conterminous U.S. every 6 years. In addition, the USGS intermittently creates or updates models for other regions such as Alaska, Hawaii, and other U.S. territories, and periodically produces models for other countries. These models are intended for use with the USGS probabilistic earthquake hazard codebase: [*nshmp-haz*](https://github.com/usgs/nshmp-haz).
+
+Each model region and year has a dedicated repository:
+* [Conterminous US (2014)](/usgs/nshm-cous-2014)
+* [Conterminous US (2008)](/usgs/nshm-cous-2008)
+* [Alaska (2007)](/usgs/nshm-ak-2007)
+
+See also:
+* [USGS Earthquake Hazards website](http://earthquake.usgs.gov/hazards/)
+
+### Go to the [examples](/usgs/nshmp-haz/tree/master/etc/examples) ...or return [home](home).
diff --git a/docs/What-is-Epsilon?.md b/docs/What-is-Epsilon?.md
new file mode 100644
index 000000000..88192e431
--- /dev/null
+++ b/docs/What-is-Epsilon?.md
@@ -0,0 +1,7 @@
+
+*TODO need about-deaggregation; check Ex 7 link*
+
+### What are ε and ε₀?
+
+The ground motion, _Y_, that might be recorded at a specific site from an earthquake 'source' with a given magnitude and distance is typically modeled as a log-normal variate such that the logarithm of _Y_, which we denote _y_, has a normal distribution, with mean, _μ_, and standard deviation, _σ_. Epsilon is defined as the standardized _y_ at a site from a specific source: _ε_ = (_y_ – _μ_) ∕ _σ_. Because we compute the probability of exceeding some ground motion at a site, _p₀_, in probabilisitic seismic hazard analysis, our deaggregation tools instead report _ε₀_ = (_y₀_ – _μ_) ∕ _σ_.
+
diff --git a/docs/_Footer.md b/docs/_Footer.md
new file mode 100644
index 000000000..2d4ca388b
--- /dev/null
+++ b/docs/_Footer.md
@@ -0,0 +1 @@
+[<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/_Sidebar.md b/docs/_Sidebar.md
new file mode 100644
index 000000000..82cfa25b9
--- /dev/null
+++ b/docs/_Sidebar.md
@@ -0,0 +1,13 @@
+[Home](home)
+[Building & Running](building-&-running)
+ – [Configuration](configuration)
+ – [Site Specification](sites)
+[Source Models](source-models)
+ – [Source Types](source-types)
+ – [Ground Motion Models](ground-motion-models)
+ – [USGS Models](usgs-models)
+[Examples](https://github.com/usgs/nshmp-haz/tree/master/etc/examples)
+[Dependencies & Development](dependencies-&-development)
+[Functional PSHA](functional-psha)
+[API Docs](http://usgs.github.io/nshmp-haz/javadoc)
+[License](https://github.com/usgs/nshmp-haz/blob/master/LICENSE.md)
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
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
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
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
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