Building-&-Running.md

# Building & Running

[TOC]

## Build and Run Locally

Building and running *nshmp-haz* requires prior installation of Git and Java. Please see the
[developer basics](./Developer-Basics.md) page for system configuration guidance.  

### Building

*nshmp-haz* uses the [Gradle](https://gradle.org/) build tool. 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.

### Running

*nshmp-haz* applications may be run from the command line or as a local web service. Command line
applications are recommended for long running hazard and disaggregation calculations, but most
users will find the web service endpoints to be more flexible. Web services return
[JSON](https://www.json.org/json-en.html) responses that can be parsed by most programming
languages and data analaysis and visualization programs (e.g. Matlab).

### Web Services

To run *nshmp-haz* web services:

```bash
./gradlew run
# or './gradlew run -t' to recompile and relaunch when code changes
```

By default, when the web services start up, they load the 2018 NSHM for the conterminous U.S.
To use a different model run the web services using Java and specify model path:

```bash
./gradlew assemble
java -jar build/libs/nshmp-haz.jar --model=path/to/model
```

After startup, web services and documentation are available at <http://localhost:8080/>.

See the [Matlab](../../etc/matlab) directory for examples of how to call the web services. To
run the ground motion model (GMM) web services, please use the
[*nshmp-haz-ws*](https://code.usgs.gov/ghsc/nshmp/nshmp-ws) repository.

### Command Line Hazard Calculation

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.md) and the
[site](./Site-Specification.md)(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.md) 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.md) values are used.

See the [examples](../../etc/examples) directory for more details.

### Command Line Disaggregation Calculation

Like `HazardCalc`, the `DisaggCalc` program performs disaggregations at one or more sites for a
variety of intensity measures. The return period for the disaggregation is defined in the config,
see [`disagg.returnPeriod`](./Calculation-Configuration.md#calculation-configuration-parameters).
Example:

```bash
java -cp nshmp-haz.jar gov.usgs.earthquake.nshmp.DisaggCalc model sites [config]
```

Disaggregations build on and output `HazardCalc` results along with other disaggregation specific
files. Disaggregations also have some independent
[configuration](./Calculation-Configuration.md#calculation-configuration-parameters) options.

Windows users may run into errors caused by unicode characters in the disaggregation configuration
options. As a work around, add `-Dfile.encoding="UTF-8"` to the java call (see
[example 7](../../etc/examples/7-disaggregation/README.md) for more details).

## Customizing Code

Whereas *nshmp-haz* contains code to run command line applications and web services, model
loading and hazard 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*, set an environment variable `NSHMP_LIB_LOCAL=true` and *nshmp-haz*
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). When using a local version
of *nshmp-lib*, first build the *nshmp-lib* project using `./gradlew fatJar` so that
required dependencies are included.

Summary of steps to check out and start running code for local development:

```bash
# --> Set a NSHMP_LIB_LOCAL=true environment variable on your system
cd yourProjectDirectory
git clone https://code.usgs.gov/ghsc/nshmp/nshmp-lib.git
cd nshmp-lib
./gradlew fatJar
cd ..
git clone https://code.usgs.gov/ghsc/nshmp/nshmp-haz.git
cd nshmp-haz
./gradlew run
```

---

## Related Pages

* [Building & Running](./Building-&-Running.md#building-&-running)
  * [Developer Basics](./Developer-Basics.md#developer-basics)
  * [Calculation Configuration](./Calculation-Configuration.md#calculation-configuration)
  * [Site Specification](./Site-Specification.md#site-specification)
  * [Using Docker](./Using-Docker.md#using-docker)
  * See also the [examples](../../etc/examples) directory
* [**Documentation Index**](../README.md)

---
![USGS logo](./images/usgs-icon.png) &nbsp;[U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))