Configuration

A config.json file resides at the root of every source model.

This file supplies model initialization and default calculation configuration parameters; see the examples directory, or any USGS model, for examples.

The file must be composed of well-formed JSON. Why 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.

Parameter	Type	Notes
model
.name	String
.surfaceSpacing	Double	(in km)
.ruptureFloating	String	RuptureFloating
.ruptureVariability	Boolean
.pointSourceType	String	PointSourceType
.areaGridScaling	String	AreaSource.GridScaling

Calculation Configuration Parameters

Calculation configuration parameters are optional (i.e. defaults are used for missing values) and overridable. Please see building and running for details on how to override a calculation configuration.

Parameter	Type	Default	Notes
hazard
.exceedanceModel	String	TRUNCATION_UPPER_ONLY	ExceedanceModel
.truncationLevel	Double	3.0
.imts	String[]	[ PGA, SAOP2, SA1P0 ]	Imt
.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 ] 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
.gmmUncertainty	Boolean	false	1️⃣
.valueFormat	String	ANNUAL_RATE	ValueFormat
deagg			2️⃣
.bins	Object
.contributorLimit	Double	0.1
rate
.bins	Object		3️⃣
.distance	Double	20 km
.distributionFormat	String	INCREMENTAL	DistributionFormat
.timespan	Double	30 years
.valueFormat	String		ValueFormat
site
.vs30	Double	760.0	Site
.vsInferred	Boolean	true
.z1p0	Double	null or NaN	4️⃣
.z2p5	Double	null or NaN	4️⃣
output
.directory	String	curves/ (in working directory)
.dataTypes	String[]	[ TOTAL ]	DataType
.flushLimit	Integer	5	5️⃣
performance
.optimizeGrids	Boolean	true	6️⃣
.collapseMfds	Boolean	true	7️⃣
.systemPartition	Integer	1000	8️⃣
.threadCount	String	ALL	ThreadCount

1️⃣ hazard.gmmUncertainty

If values for additional epistemic uncertainty on ground motion have been defined, this value en/disables this feature.

2️⃣ 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:

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

3️⃣ rate.bins

The rate.bins field is mapped to a data container that specifies the following default magnitude binning range and interval:

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

4️⃣ 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.

5️⃣ output.flushLimit

The number of results to write at a time. More memory is required for higher limits.

6️⃣ 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.

7️⃣ performance.collapseMfds

Some magnitude-frequency distribution logic-trees can be combined. This is currently always true.

8️⃣ 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