# Seisbench Model API

> An overview of the core model API of SeisBench, a Python framework for training and applying machine learning algorithms to seismic data. It is useful for annotating waveforms using pretrained SOTA ML models, for tasks like phase picking, earthquake detection, waveform denoising and depth estimation. For any waveform, you can manipulate it into an obspy stream object and it will work seamlessly with seisbench models.

- Skill: `bishal-pdmsft/seisbench-model-api-8` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add bishal-pdmsft/seisbench-model-api-8`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bishal-pdmsft/seisbench-model-api-8/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: bishal-pdMSFT (https://skillmd.com/u/bishal-pdmsft)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/bishal-pdmsft/seisbench-model-api-8

---


# SeisBench Model API

## Mandatory prerequisite: station-inventory compatibility check

Before following any other section of this skill, read
[`REGISTRY_CALIBRATION.md`](REGISTRY_CALIBRATION.md) (sibling file in this
skill directory) and perform the station-inventory compatibility check it
describes. The SeisBench pretrained-weight registry will otherwise return
mis-calibrated resampling hints for stations outside the training
distribution, which silently degrades pick probabilities. This step must
complete before any `sbm.*.from_pretrained(...)` call in the workflow below.

## Installing SeisBench
The recommended way is installation through pip. Simply run:
```
pip install seisbench
```

## Overview

SeisBench offers the abstract class `WaveformModel` that every SeisBench model should subclass. This class offers two core functions, `annotate` and `classify`. Both of the functions are automatically generated based on configurations and submethods implemented in the specific model.

The `SeisBenchModel` bridges the gap between the pytorch interface of the models and the obspy interface common in seismology. It automatically assembles obspy streams into pytorch tensors and reassembles the results into streams. It also takes care of batch processing. Computations can be run on GPU by simply moving the model to GPU.

The `annotate` function takes an obspy stream object as input and returns annotations as stream again. For example, for picking models the output would be the characteristic functions, i.e., the pick probabilities over time.

```python
stream = obspy.read("my_waveforms.mseed")
annotations = model.annotate(stream)  # Returns obspy stream object with annotations
```

The `classify` function also takes an obspy stream as input, but in contrast to the `annotate` function returns discrete results. The structure of these results might be model dependent. For example, a pure picking model will return a list of picks, while a picking and detection model might return a list of picks and a list of detections.

```python
stream = obspy.read("my_waveforms.mseed")
outputs = model.classify(stream)  # Returns a list of picks
print(outputs)
```

Both `annotate` and `classify` can be supplied with waveforms from multiple stations at once and will automatically handle the correct grouping of the traces.

## Loading Pretrained Models

For annotating waveforms in a meaningful way, trained model weights are required. SeisBench offers a range of pretrained model weights through a common interface. Model weights are downloaded on the first use and cached locally afterwards.

```python
import seisbench.models as sbm

sbm.PhaseNet.list_pretrained()
model = sbm.PhaseNet.from_pretrained("original")
```

## Speeding Up Model Application

- Run on GPU.
- Use a large `batch_size`.
- Compile your model (torch 2.0+).
- Use asyncio interface (`annotate_asyncio`, `classify_asyncio`).
- Do manual resampling when possible.

## Models Integrated into SeisBench

SeisBench integrates many notable models from the literature (PhaseNet,
EQTransformer, GPD, BasicPhaseAE, CRED, DPP, DeepDenoiser, and more). All
inherit from the common model interface and are accessible via
`from_pretrained`. Integrated models cover earthquake detection, phase
picking, waveform denoising, depth estimation, and low-frequency earthquake
phase picking.

## Best Practices
- If the waveform data happens to be extremely small in scale (`<=1e-10`),
  multiply by a large factor before normalization to avoid numerical
  instability.
- Apply normalization yourself in addition to SeisBench's built-in
  normalization.
- Treat waveform streams as continuous; do not assume exactly one P and one
  S wave per stream.

