ShakeMap grid¶

ingv_shakemap.grid ¶

A ShakeMap grid.xml, read into numbers you can sample at any point.

Pure: nothing here does I/O.

The format (ShakeMap 4, checked on INGV files in October and November 2026):

a root <shakemap_grid> with the map's version and map_status (automatic until a seismologist reviews it);
an <event> with magnitude, depth, epicentre and time;
a <grid_specification> with the extent, nlon and nlat. The step changes from event to event (about 90 m at Campi Flegrei, 0.0083° ≈ 900 m elsewhere);
one <grid_field> per column (LON, LAT, MMI, PGA, PGV, PSA03, PSA10, PSA30, SVEL), each with its unit;
a <grid_data> of nlon * nlat rows, from the north edge southwards, longitude fastest.

Two traps. PGA and the PSA columns are in percent of g, not in g: 0.11 is a barely felt 0.0011 g. And the row order is a convention of the format, not something the file states, so :func:parse_grid checks it on the first rows instead of assuming it: a different order would move every value.

A big event's grid is 10-12 MB of text; parsing it takes a few hundred milliseconds, so call :func:parse_grid in a thread from async code.

GridError ¶

Bases: IngvError, ValueError

A grid.xml that is not a readable ShakeMap grid.

GridField `dataclass` ¶

One column of the grid.

GridEvent `dataclass` ¶

The earthquake a grid is about, as the grid itself describes it.

ShakeGrid `dataclass` ¶

The ground shaking of one event on a regular lon/lat grid.

bbox `property` ¶

bbox: tuple[float, float, float, float]

West, south, east, north of the grid's points.

value_at ¶

value_at(name: str, longitude: float, latitude: float) -> float | None

Column name at the grid point nearest to a position, in its native unit.

None outside the grid. Raises :class:GridError for a column the grid does not have.

pga_g ¶

pga_g(longitude: float, latitude: float) -> float | None

Peak ground acceleration at a position, in g (not percent of g).

pgv_cm_s ¶

pgv_cm_s(longitude: float, latitude: float) -> float | None

Peak ground velocity at a position, in cm/s.

mmi ¶

mmi(longitude: float, latitude: float) -> float | None

Macroseismic intensity at a position (Modified Mercalli).

column ¶

column(name: str) -> npt.NDArray[np.float64]

Column name as an (nlat, nlon) array, north row first, native unit.

sample ¶

sample(name: str, longitudes: ArrayLike, latitudes: ArrayLike, *, method: Literal['nearest', 'bilinear'] = 'nearest') -> npt.NDArray[np.float64]

Column name at many positions at once, in its native unit.

nearest gives exactly what :meth:value_at gives, point by point (ties round half to even, as Python's round). bilinear interpolates between the four surrounding grid points and is defined only inside :attr:bbox. Positions outside the grid are NaN.

sample_g ¶

sample_g(name: str, longitudes: ArrayLike, latitudes: ArrayLike, *, method: Literal['nearest', 'bilinear'] = 'nearest') -> npt.NDArray[np.float64]

An acceleration column (PGA, PSA03...) at many positions, in g.

parse_grid ¶

parse_grid(xml: bytes | str) -> ShakeGrid

A grid.xml as a :class:ShakeGrid; raises only :class:GridError.