Newer
Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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)