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