# Historical earthquakes: a real ShakeMap over your places

The model lab's `openquake-shakemap` lane answers one question: what would
the shaking of a real earthquake do to your places today? It takes the
USGS ShakeMap of one of ten historical earthquakes, the map of how hard
the ground shook, built from that earthquake's seismic recordings and felt
reports, and runs it through the OpenQuake engine over your schedule.
Every lab model is an open model, run as its authors published it on fixed
inputs. Craton has not validated it. How to reach the lab is in
[the agent walk](agents.md); what each figure means is in
[lab metrics](lab-metrics.md).

## The earthquakes

The lane runs a closed list. Each earthquake's ShakeMap is the one the USGS
catalog (ComCat) marks preferred, pinned by its product address and its
sha256, so a run always reads the same map. `GET
https://lab.oncraton.com/models` lists them with the same fields.

| `event` | Earthquake | Date (local) | Magnitude | Region |
|---|---|---|---|---|
| `northridge-1994` | Northridge | 1994-01-17 | 6.7 | San Fernando Valley, Los Angeles, California |
| `loma-prieta-1989` | Loma Prieta | 1989-10-17 | 6.9 | Santa Cruz Mountains, San Francisco Bay Area, California |
| `nisqually-2001` | Nisqually | 2001-02-28 | 6.8 | Puget Sound, Washington |
| `south-napa-2014` | South Napa | 2014-08-24 | 6.0 | Napa Valley, California |
| `ridgecrest-2019` | Ridgecrest | 2019-07-05 | 7.1 | Searles Valley near Ridgecrest, California |
| `anchorage-2018` | Anchorage | 2018-11-30 | 7.1 | Anchorage, Alaska |
| `puerto-rico-2020` | Puerto Rico | 2020-01-07 | 6.4 | Southwest Puerto Rico |
| `kaikoura-2016` | Kaikoura | 2016-11-14 | 7.8 | Canterbury and Marlborough, New Zealand |
| `kahramanmaras-2023` | Kahramanmaras | 2023-02-06 | 7.8 | Southern Turkey and northern Syria |
| `tohoku-2011` | Tohoku | 2011-03-11 | 9.1 | Off the Pacific coast of Tohoku, Japan |

Ridgecrest is the M7.1 mainshock alone, without the M6.4 foreshock of the
day before; Kahramanmaras is the M7.8 mainshock alone, without the M7.5
earthquake about nine hours later. Tohoku's figures are shaking damage
only: its tsunami, which caused most of the deaths and much of the damage,
is not modeled. Each of these results says so in a warning.

## Run one

Send the spec to `https://lab.oncraton.com/runs` (or as `arguments.spec` on
a `run_climate_model` call over MCP), with your key:

```json
{
  "model": "openquake-shakemap",
  "event": "northridge-1994",
  "vulnerability": "hazus_c1m_moderate_code",
  "exposure": {"points": [
    {"lat": 34.1511, "lon": -118.449, "value": 5000000},
    {"lat": 34.0195, "lon": -118.4912, "value": 5000000}
  ]}
}
```

`event` is required and must be one of the ids above; there is no rupture
to describe and no USGS id to pass. `vulnerability` is optional and takes
the same five curves as the earthquake scenario lane, with the same
default: `hazus_c1m_moderate_code`, `hazus_c1m_high_code` and
`hazus_c1m_pre_code` (HAZUS 5.1 mid-rise concrete frames), or the engine's
Nepal demonstration curves `demo_nonengineered_concrete` and `demo_wood`.
Up to 500 places, or `exposure: {"object_id": ...}` for a stored object's
own schedule. The same spec is the same content-addressed run, replayed
from the store.

## What comes back

The result keeps the earthquake scenario lane's shape, so a reader of one
reads the other. For the spec above (Sherman Oaks and Santa Monica, $5
million each, stored under version `openquake-3.26.2-shakemap-r1`):

- `total_mean_loss` and `metrics.loss_mean`: $3,490,880, the mean loss over
  100 shaking patterns. `metrics.loss_ratio`: a mean of 34.9% of the value,
  19.6% in the mildest tenth of patterns (`p10`) and 49.3% in the worst
  tenth (`p90`).
- `metrics.per_point`, for each place: `loss_mean`, `loss_ratio` and its
  spread across the patterns (`loss_ratio_p10`, `loss_ratio_p50`,
  `loss_ratio_p90`); the shaking as peak ground acceleration in g, both as
  `pga_geometric_mean_g` (the engine's own average) and
  `pga_arithmetic_mean_g`, which is higher; and the ShakeMap's own value at
  that place, `pga_shakemap_g` and `mmi_shakemap` (Modified Mercalli
  intensity), with the USGS words for it in `shaking`. Sherman Oaks: the
  ShakeMap reads 0.53 g, intensity 8.4, "severe"; the patterns average
  0.52 g; the mean loss is $1,818,690 (36.4%), from 18.0% to 55.9% across
  the patterns.
- `metrics.vulnerability_sensitivity`: the same patterns through every
  curve. Here: 19.3% for high-code concrete, 34.9% moderate code, 66.3%
  pre-code.
- `metrics.event` and `result.event`: which earthquake, and the ShakeMap
  product, its addresses and digests.
- `assumptions` and `warnings`, as plain sentences.

There is no average annual loss and no return period: one earthquake has
no frequency attached. `metrics.basis` is `scenario`, like the scenario
lane; the run document's `basis` says "observed history".

Two more of the lab's own runs: Ridgecrest over one $10 million building in
Ridgecrest, 0.38 g and intensity 7.2 on the ShakeMap, a mean loss of
$2,325,370 (23.3%); Tohoku over one $10 million building in Sendai, 0.67 g
and intensity 7.8, a mean loss of $4,295,960 (43.0%).

## How the lab computes it

1. **The ShakeMap.** Each ShakeMap is two grids from the USGS: the shaking
   at every node (`grid.xml`) and its uncertainty (`uncertainty.xml`),
   which is smallest near the recording stations. The lab checks both
   files against their pinned sha256 before every run and reads them from
   disk; it never fetches a ShakeMap at run time.
2. **100 shaking patterns.** The OpenQuake engine samples 100 ground-motion
   fields around the ShakeMap's values, spread by its uncertainty and
   correlated in space (Jayaram and Baker 2009), so neighbors shake alike.
   The sampling is seeded, single-process and truncated at three standard
   deviations. Local ground conditions are the ShakeMap's own.
3. **Loss.** Each pattern's peak ground acceleration at each place goes
   through the chosen curve. The curves read only peak ground acceleration,
   so the ShakeMap's spectral accelerations are not used.

The lab's figures carry the engine's six significant digits.

## Where it applies

Each ShakeMap covers a rectangle around its epicenter, from about 330 km
across (South Napa) to about 1,600 km (Tohoku); `/models` gives each
rectangle as `grid`. A place outside the chosen earthquake's rectangle is
never sent to the engine and comes back `modeled: false`, counted in
`locations.unmodeled` and named in an `unmodeled_points` warning. Kaikoura's
rectangle crosses the 180th meridian, and the lab handles that. If no place
is inside, the run still succeeds, every place is unmodeled, and there is
no `metrics` block: nothing was measured, so there is no figure to show.

## What it leaves out

Ground-up losses only, to buildings only. Shaking only: fire following,
liquefaction, landslide and tsunami are not modeled. One curve for every
place. No demand surge. The figures are what that day's shaking would do to
the values you send, not what the earthquake cost when it happened. Every
result lists these as `assumptions`.

## Replaying a result

The ten earthquakes and the digests of their twenty ShakeMap files live in
one pinned manifest, recorded with its own digest in every run id (the
`events` input). The OpenQuake engine and the curves are the scenario
lane's, pinned the same way. Repeat runs of the same spec give the same
bytes, on either kind of machine the lab rents.