From b9ebbccc4defc782e912a21168fee28205d230ac Mon Sep 17 00:00:00 2001
From: Peter Powers <pmpowers@usgs.gov>
Date: Thu, 19 Jan 2023 12:16:55 -0700
Subject: [PATCH] updated readme
---
README.md | 140 +++++++-----------------------------------------------
1 file changed, 18 insertions(+), 122 deletions(-)
diff --git a/README.md b/README.md
index 7d6cd23..66edd7e 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,10 @@
# nshmp-ws
+*nshmp-ws* provides web service access to ground motion models (GMMs) used in USGS National Seismic
+Hazard Models (NSHMs).
+
+[TOC]
+
## Running the Services
### Gradle
@@ -8,42 +13,31 @@ To run the services with Gradle:
```bash
./gradlew run
+# or './gradlew run -t' to recompile and relaunch when code changes
```
-Services are then avialable on <http://localhost:8080/>
-
-To have the services automatically recompile when changes are made locally to the source
-code, run:
-
-```bash
-./gradlew run -t
-```
-
-### Jar file
-
-The services can be run from the JAR file:
+Alternatively, the services can be run from the JAR file:
```bash
./gradlew assemble
java -jar build/libs/nshmp-ws-all.jar
```
-Services are then avialable on <http://localhost:8080/>
+After startup, web services and documentation are available at <http://localhost:8080/>.
-Note: By default the web services use the
-[nshm-fault-sections](https://code.usgs.gov/ghsc/nshmp/nshm-fault-sections) repository in the `libs`
-directory in the root of this project and such the `java -jar` command should also be run
-in the root of the project. To run the JAR file from anywhere the path to the fault sections
-should be specified:
+#### Customizing Code
-```bash
-./gradlew assemble
-java -jar path/to/nshmp-ws-all.jar --faults-path=path/to/nshm-fault-sections
-```
+It is not uncommon for users to want to customize the behavior of the code. Whereas *nshmp-ws*
+contains code to run web services, ground motion model (GMM) calculations are handled in the
+dependent library [*nshmp-lib*](https://code.usgs.gov/ghsc/nshmp/nshmp-lib). To use a local,
+modified version of *nshmp-lib*, one need only to set an environment variable
+`NSHMP_LIB_LOCAL=true` and *nshmp-ws* will look for *nshmp-lib* in a directory adjacent to
+*nshmp-haz*. If *nshmp-lib* is located somewhere else, modify the path specified in
+[`gradle/dependencies.gradle`](../../gradle/dependencies.gradle).
### Docker
-### Run from GitLab Registry
+#### Run from GitLab Registry
The nshmp-ws application may be run as a Docker container.
@@ -73,108 +67,10 @@ http://localhost:8080/nshmp/data/fault-sections
The `PORT` should be replaced with the same value to start the container.
-### Build Docker Locally
+#### Build Docker Locally
A Docker image can also be created locally:
```bash
docker build -t <tag name> .
```
-
-## Fault Sections Service
-
-### Fault Sections Service: Usage
-
-* /nshmp/data/fault-sections
-
-### Obtaining fault sections
-
-See [nshm-fault-sections](https://code.usgs.gov/ghsc/nshmp/nshm-fault-sections)
-for information on groups and ids.
-
-#### By Group
-
-* Format: /nshmp/data/fault-sections?group={String}&raw={Boolean}
-* Format: /nshmp/data/{group}/{raw}
-* Example: /nshmp/data/fault-sections?group=CA
-* Example: /nshmp/data/fault-sections?group=CA&group=NV&group=...
-* Example: /nshmp/data/fault-sections/CA
-
-Where `group` can either be a
-[`UsRegion`](https://earthquake.usgs.gov/nshmp/docs/nshmp-lib/gov/usgs/earthquake/nshmp/internal/UsRegion.html)
-or [`FaultGroup`](https://code.usgs.gov/ghsc/nshmp/nshmp-ws/-/blob/main/src/main/java/gov/usgs/earthquake/nshmp/www/fault/FaultGroup.java).
-
-By default the `raw` flag is set to `false`, when set to `true` the response is pure GeoJSON
-
-#### By ID
-
-* Format: /nshmp/data/fault-sections?id={Integer}&raw={Boolean}
-* Example: /nshmp/data/fault-sections?id=1
-* Example: /nshmp/data/fault-sections?id=1&id=2&id=...
-
-* Format: /nshmp/data/fault-sections/{id}/{raw}
-* Example: /nshmp/data/fault-sections/1
-
-### Local Development
-
-The [fault sections repository](https://code.usgs.gov/ghsc/nshmp/nshm-fault-sections)
-repository is downloaded from a tagged version, see [gradle.properties](gradle.properties)
-`nshmFaultSectionsTag` for tagged version used, and stored in the libs directory.
-
-To, instead, point to a local version of the fault sections repository update the
-gradle.properties file, either in this project or under `$GRADLE_USER_HOME`/gradle.properties
-(defaults to `$USER_HOME/.gradle`), with the following:
-
-```bash
-faultSectionsEnv = DEV
-```
-
-Run `./gradlew clean` to clean up the libs directory and make a symbolinc link from the
-fault sections repository to the libs directory.
-Example:
-
-```bash
-cd libs
-ln -s ../nshm-fault-sections .
-```
-
-## GPS Data Service
-
-GPS data service provides access to the GPS datasets used for each NSHM. All velocities are
-in units of mm/yr and the vertical component, if available, is positive up.
-
-### GPS Data Service: Usage
-
-Datasets are selected by model:
-
-* `CONUS_2014_UCERF`
-* `CONUS_2014_WUS`
-* `AK_2020`
-* `HI_2020`
-
-Data format is one of the following:
-
-* `CSV` (default)
-* `JSON` (GeoJSON feature collection embedded in JSON response)
-* `RAW_JSON` (GeoJSON feature collection)
-
-#### GPS Data: Query-based
-
-* Format: /nshmp/data/gps?model={MODEL}&format={FORMAT}
-* Example: /nshmp/data/gps?model=HI_2020&format=CSV
-
-#### GPS Data: Slash-delimited based
-
-* Format: /nshmp/data/gps/{MODEL}/{FORMAT}
-* Example: /nshmp/data/gps/HI_2020/JSON
-
-### Geodesy Process
-
-TODO: expand process description
-
-* In house multi-modeling capability
-* Curate/update strain vector fields
-* Connectivity in fault models
-* Data transfer
- * Modifications to fault models required by geodetic modelers need to be communicated back to NSHM
-* slip rate uncertainties
--
GitLab