Building & Running

Overview

• Build and Run Locally
• Run with Docker

Build and Run Locally

Build Requirments

Building and running nshmp-haz requires prior installation of Git and Java.
Please see this 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:

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 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:

java -cp nshmp-haz.jar gov.usgs.earthquake.nshmp.HazardCalc model sites [config]

At a minimum, the source model and the site(s) 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 file. Under the 2-argument scenario, model initialization and calculation configuration settings are drawn from the 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 directory for more details.

Computing Deaggregations

Like HazardCalc, The DeaggCalc program performs deaggregations at one or more sites for a variety of intensity measures, but requires an additional returnPeriod argument, in years. For example:

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 options.

Computing Earthquake Rates and Probabilities

TODO

Matlab Access

Another convenient way to use the nshmp-haz library is via Matlab. A sample script contains the necessary instructions.

Run with Docker

Build Requirments

• Docker

Getting Latest Docker Image

To ensure you are on the latest nshmp-haz update, pull the image from Docker:

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 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:

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
  • hazard = HazardCalc
  • rate = RateCalc

• MODEL is the USGS model to run with:

  • CEUS-2018 or WUS-2018: Conterminous U.S. 2018
  • CEUS-2014 or WUS-2014: Conterminous U.S. 2014
  • CEUS-2008 or WUS-2008: Conterminous U.S. 2008
  • AK-2007: Alaska 2007

• RETURN_PERIOD, in years, is only required when running a deaggregation

• The site(s) 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 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):

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