Source Models
Sources are representations of earthquakes that occur with some rate. They can be well defined faults with a specific geometry, or point sources derived from historic earthquake catalogs for which planar pseudo-fault representations are used. In either case, there may be multiple earthquake sizes associated with a given source.
An earthquake source model, or [HazardModel] (/pmpowers-usgs/nshmp-haz/blob/master/src/org/opensha/eq/model/HazardModel.java), is specified using XML files grouped in folders by source type. The currently supported source types are:
[ Area, Cluster, Fault, Grid, Interface, Slab, System ]
One level of nested folders is permitted to facilitate logical source groups and the use of different ground motion models (GMMs). Source files, except those for Fault System Sources, and nested source group folders may be given any name. Ground motions are computed using the models defined in the gmm.xml file in each source directory. If a source group does not contain gmm.xml, one is required in the parent source type folder.
/ModelDirectory
config.json
/Fault <---------- source type
faultSources1.xml
faultSources2.xml
...
gmm.xml
/FaultGroup <--------- source group
otherFaultSources.xml
gmm.xml
/Grid
gridSources.xml
...
gmm.xml <-- uses parent GMMs --
/GridGroup1 |
otherGridSources.xml ------
/GridGroup2
otherGridSources.xml
gmm.xml
...
TODO update to JSON format - note that config settings are (or will) not likely be tied to logic tree variants.
All general properties of a Hazard Model that are not region, source type, or otherwise source specific are read from config.properties at the root of a model directory. If no configuration file is supplied, default values are used. Current defaults are:
GRIDDED_SURFACE_UNIT = 1.0
AREA_SOURCE_SCALING = SCALED_LARGE
RUPTURE_FLOATING_MODEL = NSHM
See also the examples directory.
A source requires a description of the sizes and rates of all earthquakes it is capable of generating, otherwise known as a magnitude-frequency distribution. For conciseness, all source files may supply default MFDs so that individual sources need only specify those attributes that are different from the default. Types:
- Single
- Gutenberg-Richter
- Tapered Gutenberg-Richter
- Incremental
<!-- Single magnitude MFD
- Used to represent the rupture of a specific size event on a
fault; historically this may have been referred to as a
'characteristic' rupture.
- Can float on or fill source. -->
<IncrementalMfd type="SINGLE"
a="1.0" floats="[true | false]" m="6.5" weight="0.25" />
<!-- Gutenberg-Richter MFD
- Used to represent a range of evenly discretized magnitude events
with systematically varying rates.
- Always floats when used for a fault source; never floats for grid
sources.
- 'a' is the incremental log10(number of M=0 events). -->
<IncrementalMfd type="GR"
a="1.0" b="1.0" dMag="0.1" mMin="5.0" mMax="7.0" weight="0.25" />
<!-- Tapered Gutenberg-Richter MFD
- Same as Gutenberg-Richter, above, but with an exponential taper
applied to the cumulative number of events with seismic moment
greater than M.
- Only used for grid sources. -->
<IncrementalMfd type="GR_TAPER"
a="1.0" b="1.0" dMag="0.1" mCut="6.5" mMin="5.0" mMax="7.0" weight="0.25" />
<!-- Incremental MFD
- General purpose MFD that consists of varying magnitudes and rates. -->
<IncrementalMfd type="INCR"
mags="[5.05, 5.15, ...]" rates="[1.0e-2, 0.9e-2, ...]"
floats="[true | false]" weight="0.25" />Fault-based sources commonly require a model that describes the geometry of partial (or floating) ruptures. Likewise, grid sources require a model of fault-length or -area when building pseudo-faults or performing point source distance corrections that consider magnitude-dependent rupture sizes with unkown strike. Such models are composed of published magnitude-length or -area relations and restrictions on aspect-ratio and/or maximum rupture width that are independent of the published model.
See the API Docs for details on specific model combinations and implementations. A rupture scaling model is always sepcified as an attribute of <SourceProperties />; see examples below.
A rupture floating model manages how partial ruptures are floated across a fault source surface. See the API Docs for details on specific models. A rupture floating model is currently applied as a model configuration property.
Source files are written in plain old XML. All attributes present in the examples below are required. Exception: MFD's for specific sources may omit those attributes for which a reference, or default, MFD has been supplied; see examples below.
A note on value types: Most attribute values or element content are parsed as a String, Double, Double[] (array) or Boolean; those attribute values in ALL_CAPS are parsed as enum types and are case sensitive.
A note on using default MFDs: Default MFDs, if present, must be fully specified. Any MFD encountered in a source will map all missing attributes from the default of the same type. If no default for an MFD type is present, the source MFD must be fully specified.
TODO: source builders
Area sources are similar to Grid Sources except that a single MFD applies to an entire area with rates proportionally scaled for use at all grid nodes. See API Docs for details on area source grid scaling.
<?xml version="1.0" encoding="UTF-8"?>
<AreaSourceSet name="Source Set Name" weight="1.0">
<!-- Settings block for any data that applies to all sources. -->
<Settings>
<!-- (optional) The reference MFDs to use. -->
<DefaultMfds>
<IncrementalMfd type="GR"
a="0.0" b="0.8" dMag="0.1" mMax="7.0" mMin="5.0" weight="1.0" />
...
</DefaultMfds>
<SourceProperties
ruptureScaling="NSHM_FAULT_WC94_LENGTH"
gridScaling="UNIFORM_0P1" />
</Settings>
<!-- Sources must follow Settings ... -->
<Source name="Area Source Name">
<!-- Specify MFDs ...
- at a minimum, 'type' must be defined, assuming a reference MFD
is present. -->
<IncrementalMfd type="GR" a="1.0e-2" dMag="0.1" mMax="7.4" />
<Geometry>
<!-- Border polygon. Individual locations specified by whitespace
separated tuples of longitude,latitude,depth (NO SPACES); same
as KML <coordintes/> format. -->
<Border>
-117.0,34.0,0.0
-117.1,34.1,0.0
-117.3,34.2,0.0
...
</Border>
</Geometry>
</Source>
<!-- Add more sources ... -->
<Source />
...
</AreaSourceSet>Cluster sources are composed of two or more fault sources that rupture independently but very closely spaced in time. Ground motions from cluster sources are modeled as the joint probability of exceeding ground motions from each independent event.
<?xml version="1.0" encoding="UTF-8"?>
<ClusterSourceSet name="Source Set Name" weight="1.0">
<!-- Settings block for any data that applies to all sources. -->
<Settings>
<!-- (optional) The reference MFD to use.
- Cluster sources only support SINGLE MFDs at this time. -->
<DefaultMfds>
<IncrementalMfd type="SINGLE"
a="0.002" floats="false" m="0.0" weight="1.0" />
</DefaultMfds>
<!-- Although not used, a rupture scaling model is required to
initalize the fault sources nested in each cluster. -->
<SourceProperties ruptureScaling="NSHM_FAULT_WC94_LENGTH" />
</Settings>
<!-- Sources must follow Settings ... -->
<Cluster name="Cluster Source Name" weight="0.2">
<Source name="Fault Source Name">
<!-- Specify MFDs; only SINGLE is supported -->
<IncrementalMfd m="6.6" type="SINGLE" weight="0.1" />
<IncrementalMfd m="6.9" type="SINGLE" weight="0.1" />
<IncrementalMfd m="7.3" type="SINGLE" weight="0.5" />
<!-- Then geometry ... -->
<Geometry dip="45.0" rake="0.0" width="14.0">
<!-- Trace must follow right-hand rule. -->
<!-- Individual locations specified by whitespace separated
tuples of longitude,latitude,depth (NO SPACES); same as
KML <coordintes/> format. -->
<Trace>
-117.0,34.0,0.0
-117.1,34.1,0.0
-117.3,34.2,0.0
...
</Trace>
</Geometry>
</Source>
</Cluster>
<!-- Add more sources ... -->
<Cluster />
...
</ClusterSourceSet><?xml version="1.0" encoding="UTF-8"?>
<FaultSourceSet name="Source Set Name" weight="1.0">
<!-- Settings block for any data that applies to all sources. -->
<Settings>
<!-- (optional) The reference MFDs to use. -->
<DefaultMfds>
<IncrementalMfd type="SINGLE"
a="0.0" floats="false" m="0.0" weight="0.6667" />
<IncrementalMfd type="GR"
a="0.0" b="0.8" dMag="0.1" mMin="5.0" mMax="7.0" weight="0.3333" />
...
</DefaultMfds>
<!-- (optional) The magnitude uncertainty model that will be applied to
every source:
- The model is only ever applied to SINGLE and GR MFDs.
- <Epistemic/> varies mMax and scales the rates by the supplied
weights.
- 'cutoff' is magnitude below which uncertainty will be disabled.
- <Aleatory/> applies a (possibly moment-balanced) ±2σ Gaussian
distribution to mMax.
- 'count' is the number of magnitude bins spanned by the distribution.
- <Aleatory/> or '<Epistemic/>', or the entire block may be
omitted. -->
<MagUncertainty>
<Epistemic cutoff="6.5"
deltas="[-0.2, 0.0, 0.2]" weights="[0.2, 0.6, 0.2]" />
<Aleatory cutoff="6.5"
moBalance="true" sigma="0.12" count="11" />
</MagUncertainty>
<SourceProperties ruptureScaling="NSHM_FAULT_WC94_LENGTH" />
</Settings>
<!-- Sources must follow Settings ... -->
<Source name="Fault Source Name">
<!-- Specify MFDs ...
- at a minimum, 'type' must be defined, assuming reference MFDs
are present. -->
<IncrementalMfd type="SINGLE" a="1.0" m="7.4" />
<IncrementalMfd type="GR" a="1.0e-2" dMag="0.1" mMax="7.4" />
<!-- Then geometry ... -->
<Geometry dip="45.0" rake="0.0" width="14.0">
<!-- Trace must follow right-hand rule. -->
<!-- Individual locations specified by whitespace separated tuples of
longitude,latitude,depth (NO SPACES); same as KML <coordintes/>
format. -->
<Trace>
-117.0,34.0,0.0
-117.1,34.1,0.0
-117.3,34.2,0.0
...
</Trace>
</Geometry>
</Source>
<!-- Add more sources ... -->
<Source />
...
</FaultSourceSet><?xml version="1.0" encoding="UTF-8"?>
<GridSourceSet name="Source Set Name" weight="1.0">
<!-- (optional) Settings block for any data that applies to all sources. -->
<Settings>
<!-- (optional) The reference MFDs to use; although optional, using
reference MFDs greatly reduces grid source file sizes. -->
<!-- (optional) The reference MFDs to use; although optional, using
reference MFDs greatly reduces grid source file sizes. -->
<DefaultMfds>
<IncrementalMfd type="GR"
a="0.0" b="0.8" dMag="0.1" mMax="7.0" mMin="5.0" weight="1.0" />
<IncrementalMfd type="INCR"
mags="[5.05, 5.25, 5.45, 5.65, 5.85, 6.05, 6.25, 6.45, 6.65]"
rates="[0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]"
weight="1.0" />
...
</DefaultMfds>
<!-- Grid sources require attitional information about the distribution
of focal mechanisms and depths to use:
- 'depthMap' is a ';' separated list cutoff magnitudes mapped to
depths and associated weights. In the example below events of
M<6.5 are located at a depth of 5 km, with a full weight of 1.
The [depth:weight] mapping may contain multiple, ',' separated
values, e.g. [6.5::[5.0:0.8,1.0:0.2], ...].
- 'mechMap' is a ',' separated list of focal mechanism identifiers
and associated wieghts.
- In both maps, weights must sum to 1.
- Use 'NaN' for unknown strike. Note that if a strike value is
defined, sources will be implementated as FIXED_STRIKE and any
configuration settings will be ignored. -->
<SourceProperties
depthMap="[6.5::[5.0:1.0]; 10.0::[1.0:1.0]]"
mechsMap="[STRIKE_SLIP:0.5,NORMAL:0.0,REVERSE:0.5]"
ruptureScaling="NSHM_POINT_WC94_LENGTH"
strike="120.0" />
</Settings>
<!-- Nodes are specialized <IncrementalMfd/> elements that specify the location
of individual grid sources and have the necessary attributes to define
the MFD for the source. -->
<Nodes>
<Node type="GR" a="0.0823" mMax="7.2">-119.0,34.0,0.0</Node>
<Node type="GR" a="0.0823" mMax="7.1">-119.1,34.0,0.0</Node>
<Node type="GR" a="0.0823" mMax="6.8">-119.2,34.0,0.0</Node>
<Node type="GR" a="0.0823" mMax="7.1">-119.3,34.0,0.0</Node>
<Node type="SINGLE" rates="[1.0e-2, 9.0e-3, ...]">-119.4,34.0,0.0</Node>
<Node type="SINGLE" rates="[1.0e-2, 9.0e-3, ...]">-119.5,34.0,0.0</Node>
<Node type="GR" a="0.0823" mMax="6.9">-119.3,34.0,0.0</Node>
...
</Nodes>
</GridSourceSet>TODO: corresponding grid source file
Fault system sources require two files: sections.xml and sources.xml that are placed together within a source group folder.
sections.xml defines the geometry of a fault network as a set of indexed fault sections:
<?xml version="1.0" encoding="UTF-8"?>
<IndexedFaultSections name="Source Set Name">
<!-- Specify section 'index' and 'name' -->
<Section index="0" name="Section Name">
<!-- Specify section geometry -->
<Geometry aseis="0.1" dip="50.0" dipDir="89.459"
lowerDepth="13.0" upperDepth="0.0">
<!-- Unlike Fault Sources, trace does not need to follow
right-hand rule as 'dipDir' is supplied above. -->
<!-- Individual locations specified by whitespace separated
tuples of longitude,latitude,depth (NO SPACES); same as
KML <coordintes/>format. -->
<Trace>
-117.75,35.74,0.00
-117.76,35.81,0.00
</Trace>
</Geometry>
</Section>
<!-- Add more sections ... -->
<Section />
</IndexedFaultSections>sources.xml defines the geometry of fault sources, referencing fault sections by index:
<?xml version="1.0" encoding="UTF-8"?>
<IndexedFaultSourceSet name="Source Set Name" weight="1.0">
<!-- <Settings/> block may be included; see Fault Sources and Grid Sources
for examples. -->
<!-- Sources must follow Settings ...
- indexed fault sources do not require a name.-->
<Source>
<!-- Specify MFDs ... -->
<IncrementalMfd a="1.0e-05" floats="false" m="6.58" type="SINGLE" weight="1.0" />
<!-- Then geometry ...
- 'indices' is an array of index ranges, ordered from one end of
the source to the other -->
<Geometry indices="[[0:5],[13:22],[104:106]" rake="0.0" />
</Source>
<!-- Add more sources ... -->
<Source />
...
</IndexedFaultSourceSet><?xml version="1.0" encoding="UTF-8"?>
<SubductionSourceSet name="Source Set Name" weight="1.0">
<!-- See Fault Sources for 'Settings' examples. -->
<Settings />
<!-- Sources must follow Settings ... -->
<Source name="Subduction Source Name">
<!-- Specify MFDs ... -->
<IncrementalMfd type="SINGLE" a="1.0" m="8.2" weight="1.0"/>
<!-- Then geometry ... -->
<Geometry rake="90.0">
<!-- As with Fault Sources, trace must follow right-hand rule. -->
<!-- Individual locations specified by whitespace separated
tuples of longitude,latitude,depth (NO SPACES); same as
KML <coordintes/> format. -->
<Trace>
-124.7,41.0,0.0
-124.6,44.0,0.0
-124.5,47.0,0.0
...
</Trace>
<!-- Subduction sources require a lower trace to be defined, also
following the right-hand-rule. -->
<LowerTrace>
-124.5,41.0,0.0
-124.4,44.0,0.0
-124.3,47.0,0.0
...
</LowerTrace>
</Geometry>
</Source>
<!-- Add more sources ... -->
<SubductionSource />
...
</SubductionSourceSet>Intraslab sources are currently specified the same way as Grid Sources.
U.S. Geological Survey – National Seismic Hazard Mapping Project (NSHMP)