Seis3C

Seis3C is a mask-aware adapter for transferring frozen time-series foundation models to synchronized three-component seismic waveforms. It encodes the Z, N, and E components with one shared backbone, preserves aligned temporal tokens, and performs component-aware fusion with explicit observation masks.

This repository contains the standalone method code extracted from TSFM-SEIS-Library. It includes the paper's Sundial, Chronos-2, and Mantis-v2 backbones; PNW and STEAD data protocols; clean, cross-condition, and cross-dataset experiment drivers; statistical bootstrap utilities; and focused tests. Datasets, model weights, experiment outputs, logs, and manuscript files are intentionally excluded.

Method Overview

Seis3C applies one shared frozen TSFM to all three synchronized components. The trainable adapter adds component-identity and observation-mask embeddings, fuses Z/N/E tokens at aligned time positions, and pools only observed components before classification.

Seismic Conditions

The evaluation distinguishes clean records from horizontal coordinate rotations and explicit missing-component conditions. Missingness is represented by an observation mask rather than inferred from waveform amplitude.

Results Snapshot

PNW earthquake-versus-explosion results across event-group splits: panel (a) compares clean Seis3C adaptation with backbone-matched concatenation; panels (b)--(d) summarize horizontal-rotation behavior, missing-component performance, and the clean-versus-robust trade-off. Error bars and bands summarize variation or paired event-cluster uncertainty as indicated by the experiment protocol.

Layout

• src/models/seis3c_adapter.py: Seis3C adapter
• src/models/: supported backbone wrappers and comparison models
• src/data/: PNW/STEAD loaders, event-group splits, crops, and seismic views
• src/finetune/seismic_classify.py: clean and robust training routines
• src/evaluation/seismic_bootstrap.py: paired event-cluster inference
• scripts/run_e1_e2_seis3c.py: single-dataset and cross-condition experiments
• scripts/run_e3_cross_dataset.py: source-only PNW/STEAD transfer
• tests/: unit and smoke-level protocol tests

Environment

Python 3.11 is recommended. Install the PyTorch build appropriate for the local CUDA runtime first, then install the remaining dependencies:

python3.11 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
# Install PyTorch from https://pytorch.org/get-started/locally/
.venv/bin/python -m pip install -r requirements.txt

SeisBench stores PNW, PNWNoise, and STEAD under its configured cache, normally ~/.seisbench/datasets/; no waveform data is stored in this repository.

Quick Check

The tests use synthetic inputs and do not download backbone weights or seismic waveforms:

.venv/bin/python -m unittest discover -v

Run a small offline E2 smoke test after the backbone weights are cached:

HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 \
  .venv/bin/python scripts/run_e1_e2_seis3c.py \
  --stage e2 --task event_type --methods seis3c_robust \
  --seeds 42 --smoke --output-dir /tmp/seis3c-smoke

Experiments

Single-dataset clean adaptation (E1):

.venv/bin/python scripts/run_e1_e2_seis3c.py \
  --stage e1 --task event_type --backbone sundial

Cross-condition robustness (E2):

.venv/bin/python scripts/run_e1_e2_seis3c.py \
  --stage e2 --task event_type --backbone sundial

Source-only cross-dataset transfer (E3):

.venv/bin/python scripts/run_e3_cross_dataset.py \
  --source stead --target pnw --backbone sundial

All formal drivers default to split seeds 42, 123, and 2024 and write outputs under results/. Use --help to inspect dataset budgets, methods, conditions, and model repository overrides.

Input Contract

Seis3CAdapter accepts x with shape (batch, 3, time) in Z/N/E order and an optional boolean component_mask with shape (batch, 3). Every sample must contain at least one observed component. Missingness must be represented by the mask; zero amplitude is not treated as an implicit missing-channel indicator.

The source project does not currently declare a software license. Add an approved license before distributing the repository publicly.