Model-Files.md

# Model Files

A variety of logic tree, configuration, and data files that are common to all models and source
types are described below and on related pages for specific model components, for example, ground
motion models (GMMs) or magnitude-frequency distributions (MFDs).

[[_TOC_]]

## Model and Calculation Configuration

**model-info.json:** Required model identifying metadata. Currently the model name and
definitions of Vs30 values for each NEHRP site class that were used when computing design ground
motions from the model.

```json
{
  "name": "NSHM Conterminous U.S. 2018",
  "site-class-vs30": {
    "AB": 1500,
    "B": 1080,
    "BC": 760,
    "C": 530,
    "CD": 365,
    "D": 260,
    "DE": 185,
    "E": 150
  }
}
```

**calc-config.json:** Optional calculation configuration file specifies the default
calculation settings used for a NSHM. This file overrides any built in default values. See
the [calculation configuration](calculation-configuration) page for more details.

## Logic Trees

Any file or JSON member name containing `-tree` implies that the file contents or member value
will be an array of logic tree branches. Branches are defined with an `id`, `weight`, and `value`.
Depending on context, value can be a number, string, or object. For example:

 ```json
 [
  {
    "id": "string",
    "value": "number | string | object",
    "weight": 0.4
  }, {
    "id": "string",
    "value": "number | string | object",
    "weight": 0.6
  }
]
```

If the `value` member is absent, then the branch `id` is also the `value`. Logic tree weights must
sum to one. Examples of logic trees present in a hazard model are described below.

### Source Model Logic Trees

**source-tree.json:** Defines a single logic tree branching point where each branch `value` points
to a subdirectory of nested branches. Source-tree weights are used to scale hazard curves when
computing mean hazard and for source event-set selection. When loading a model, a source-tree
governs all subsequent processing of nested directories. Only those resources required by the tree
or its children will be processed; any standalone sources will be ignored. For example:

```json
[
  {
    "id": "segmented",
    "weight": 0.5
  },
  {
    "id": "unsegmented",
    "weight": 0.5
  }
]
```

**source-group.json:** A specialized form of logic tree that describes model branches that are
additivd and therefore does not include weights. Examples from the NSHM for the Conterminous U.S.
NSHM include the Cascadia segmented partial-rupture models and the New Madrid 1500-yr cluster
branches. The branch objects in a source group _may_ include an optional `scale` member that can
be used to impose a probability of occurrence or other scaling requred by a NSHM. If absent, the
`scale` value is one.

```json
[
  {
    "id": "all",
    "scale": 0.2
  },
  {
    "id": "center-south",
    "scale": 1.5
  }
]
```

### GMM Logic Trees

**gmm-tree.json:** Defines the logic tree of ground motion models to use in each tectonic setting.
For example:

```json
[
  { "id": "ASK_14", "weight": 0.25 },
  { "id": "BSSA_14", "weight": 0.25 },
  { "id": "CB_14", "weight": 0.25 },
  { "id": "CY_14", "weight": 0.25 }
]
```

See the [ground motion models](ground-motion-models) page for details on GMMs supported in
_nshmp-haz_ and the related `gmm-config.json` files that governs GMM behavior.

### MFD Logic Trees

MFD logic trees are typically defined as JSON members nested in other files. For example:

```json
"mfd-tree": [
  { "id": "M1", "weight": 0.3, "value": { "type": "SINGLE", "m": 6.8, "rate": 0.001 }},
  { "id": "M2", "weight": 0.3, "value": { "type": "SINGLE", "m": 7.0, "rate": 0.001 }},
  { "id": "M3", "weight": 0.3, "value": { "type": "SINGLE", "m": 7.2, "rate": 0.001 }},
  { "id": "M4", "weight": 0.1, "value": { "type": "SINGLE", "m": 7.4, "rate": 0.001 }}
]
```

An `mfd-tree` may be included as a `properties` member of a GeoJSON feature or as a member of a
`rupture-set.json` file. In both cases the tree may alternatively be identified with a string, in
which case the `mfd-tree` will be pulled from the collection of trees defined in a `mfd-map.json`
file. A `mfd-map.json` file is typicaly located high in the source tree heirarchy and faciltates
using the same MFDs on multiple branches of a source tree.

How MFDs are intialized (or realized) depends on the presence and contents of `mfd-config.json` and
`rate-tree.json` files. See the
[magnitude frequency distributions](magnitude-frequency-distributions) page for details on these
files and the types of MFDs supported in _nshmp-haz_. 

## Rupture Sets

A `rupture-set` is the terminal file of a source-tree branch and defines the fault sections and
MFD's required to intialize a source.

**rupture-set.json**

```json
{
  "name": "New Madrid - USGS (center)",
  "id": 3023,
  "sections": [3020, 3021, 3022],
  "mfd-tree": "usgs-hi-mag"
}
```

In the example above, one set of New Madrid ruptures is assigned the specified numeric `id`. The
fault geometry of the rupture-set is constructed by stitching the specified fault `sections`
together, and earthquake magnitudes and rates are governed by the specified `mfd-tree`. In this
case, `mfd-tree` points to a named tree that will be present in an `mfd-map.json` accompanying
the source-tree. The `sections` member may be absent. In this case, the `id` of the rupture-set
is the same as the single, associated fault section.

**cluster-set.json**

Fault sources also support cluster models where the total hazard is computed from the probability
of exceeding some ground motion level is conditioned on the occurrence of 2 or more, roughly
contemporaneous events. A cluster-set is composed of an array of rupture-sets.

```json
{
  "name": "New Madrid - USGS (center, center-south)",
  "id": 3025,
  "rupture-sets": [
    {
      "name": "USGS (center, center)",
      "id": 3021,
      "mfd-tree": "usgs-hi-mag"
    },
    {
      "name": "USGS (center, south)",
      "id": 3022,
      "mfd-tree": "usgs-hi-mag"
    }
  ]
}
```