SeismicX Catalog Skill

August 6, 2026 · View on GitHub

SeismicX Catalog

SeismicX Catalog Skill

SeismicX Catalog Skill is an agent-agnostic workflow for earthquake detection and automatic catalog production. Starting with a local continuous waveform directory, it scans waveforms, detects and picks phases, associates picks, locates events, calculates local magnitude (ML), estimates focal mechanisms, summarizes activity, and plots event locations.

It is designed for Codex, OpenCode, Claude Code, and other local coding agents that can read Markdown instructions and execute local scripts.

Agent Support

  • Codex-style skill runners use the root SKILL.md.
  • OpenCode and agents following the AGENTS convention use AGENTS.md.
  • Claude Code uses CLAUDE.md.
  • Other local coding agents should read SKILL.md first, then use scripts/ and references/ as needed.

Installation

Ask a compatible agent to clone and install the repository as a skill:

Download https://github.com/cangyeone/seismicx-catalog-skill and install it as a SKILL.

The Chinese README is available from the Gitee mirror:

Download https://gitee.com/cangyeone/seismicx-catalog-skill and install it as a SKILL.

Keep the repository layout intact: SKILL.md must remain in the skill root.

Agent Usage

After installation, enter a request such as:

Build an earthquake catalog from the data in the current directory.

For a controlled production run, provide the key inputs and method choices:

Continuous waveforms are in ./waveforms, station metadata is stations.csv,
the velocity model is velocity_model.csv, and responses are in stations.xml.
Use the PNSN model to pick Pg/Sg/Pn/Sn, GaMMA for association, R13 for ML,
and write a catalog with magnitudes and focal-mechanism results.

The Agent can discover this skill automatically from the request context; users do not need to explicitly type $seismicx-catalog.

Workflow

  1. Scan MSEED, SAC, SEED, and other ObsPy-readable waveform formats.
  2. Pick user-selected phases with the bundled SeismicX PNSN TorchScript model.
  3. Associate multi-station picks with GaMMA, the bundled Python REAL backend, or a locally compiled C REAL installation.
  4. Locate events with the baseline grid solver, bayes_location, NLLoc, or SeismicX-Location.
  5. Calculate ML using seedtools-style response simulation and amplitude measurement.
  6. Estimate P-wave polarity and calculate/export focal-mechanism solutions.
  7. Write catalog, station magnitude, activity, and map products.

Important Picking Rule

Do not filter continuous waveforms before or during PNSN phase picking. The bundled model expects the original waveform stream. Filtering is appropriate only for an explicitly requested classic STA/LTA experiment or later response/amplitude processing for magnitude measurement.

Inputs

  • Waveform directory: MSEED, SAC, SEED, or any ObsPy-readable format.
  • Station table: start from assets/stations_template.csv when needed.
  • Velocity model: see assets/velocity_model_example.csv for the baseline locator.
  • Instrument response: StationXML, RESP/dataless metadata, or a seedtools response-path mapping for ML.
  • Optional local engines: C REAL, HASH/pyhash, bayes_location, NLLoc, PNSN, and seismological-ai-tools.

The repository includes compact in-house models only:

  • assets/models/pnsn.v3.jit for Pg/Sg/Pn/Sn phase picking.
  • assets/models/polar.jit for first-motion polarity workflows.

Raw waveforms, regional velocity models, generated travel-time grids, large weights, external repositories, and compiled binaries are deliberately not published with the skill.

Quick Start

Run the standard detection-to-catalog workflow:

python scripts/seismicx_catalog.py catalog \
  -w <waveforms> \
  -s stations.csv \
  -v velocity_model.csv \
  -o work/catalog_run \
  --association-method gamma

For the bundled homogeneous Python REAL associator:

python scripts/seismicx_catalog.py catalog \
  -w <waveforms> \
  -s stations.csv \
  -v velocity_model.csv \
  -o work/catalog_run \
  --association-method real \
  --real-min-score 0.2

For a step-by-step run:

python scripts/seismicx_catalog.py scan -w <waveforms> -o work/waveforms.csv
python scripts/seismicx_catalog.py pick -w <waveforms> -o work/picks.csv --picker torchscript-pnsn --model pnsn-v3 --phases Pg,Sg,Pn,Sn
python scripts/seismicx_catalog.py associate --method gamma -p work/picks.csv -s stations.csv -o work/events.csv --assignments work/assignments.csv --associated-picks work/picks_associated.csv
python scripts/seismicx_catalog.py polarity -p work/picks_associated.csv -o work/picks_with_polarity.csv
python scripts/seismicx_catalog.py locate --method grid -p work/picks_with_polarity.csv -s stations.csv -v velocity_model.csv -o work/events_located.csv
python scripts/seismicx_catalog.py magnitude-ml -e work/events_located.csv -p work/picks_with_polarity.csv -s stations.csv --inventory stations.xml --region R13 -o work/events_ml.csv --station-output work/station_ml.csv
python scripts/seismicx_catalog.py mechanism -e work/events_ml.csv -p work/picks_with_polarity.csv -s stations.csv -o work/mechanisms.csv --catalog-output work/catalog_final.csv --hash-input work/hash_input.csv

NLLoc

Use NLLoc when reviewed Grid2Time travel-time volumes are available:

python scripts/seismicx_catalog.py locate \
  --method nlloc \
  -p work/picks_with_polarity.csv \
  -s stations.csv \
  -o work/events_nlloc.csv \
  --nlloc-tt-root work/nlloc/time/tt \
  --nlloc-bin /path/to/NLLoc \
  --nlloc-workdir work/nlloc/location \
  --nlloc-workers 8

scripts/nlloc_workflow/ retains the project's Python workflow for 3D velocity preparation, slowness grids, Grid2Time, observation conversion, parallel NLLoc processing, and .hyp catalog export. It excludes regional data, generated products, and NLLoc binaries.

SeismicX-Location

SeismicX-Location is the project's local neural travel-time locator. It can train a P/S travel-time surrogate from a complete regular 3D Vp/Vs velocity grid or existing travel-time samples, then locate associated picks using bounded multi-start robust least squares.

python scripts/seismicx_location.py train \
  --stations stations.csv \
  --velocity-model velocity_3d.csv \
  --projection-origin "$SEISMICX_PROJECTION_ORIGIN" \
  --output work/seismicx_location.pt

python scripts/seismicx_catalog.py locate \
  --method seismicx-location \
  -p work/picks_with_polarity.csv -s stations.csv \
  -o work/events_seismicx.csv \
  --seismicx-location-checkpoint work/seismicx_location.pt \
  --seismicx-location-projection-origin "$SEISMICX_PROJECTION_ORIGIN"

This path is strictly local. It makes no network calls and does not store the projection origin, station coordinates, or event coordinates in its checkpoint or logs. The projection origin is supplied only at runtime, and the catalog runner redacts it from printed commands. The final catalog is written only to the local output path chosen by the user.

Optional Tools

python scripts/seismicx_catalog.py build-tools --tool pnsn --tools-dir external -o work/pnsn_manifest.json
python scripts/seismicx_catalog.py build-tools --tool bayes-location --tools-dir external -o work/bayes_manifest.json
python scripts/seismicx_catalog.py build-tools --tool seismological-ai-tools --tools-dir external -o work/ai_tools_manifest.json
python scripts/seismicx_catalog.py build-tools --tool real --tools-dir external -o work/real_manifest.json
python scripts/seismicx_catalog.py build-tools --tool hash --hash-source ./pyhash -o work/hash_build_manifest.json

Use --tool all --skip-build to download the standard external reference repositories. HASH/pyhash requires an explicit local source tree because its Fortran build differs between deployments.

Repository Layout

SKILL.md
AGENTS.md
CLAUDE.md
scripts/seismicx_catalog.py
scripts/seismicx_real.py
scripts/seismicx_nlloc.py
scripts/seismicx_location.py
scripts/nlloc_workflow/
references/
assets/
logo.png
README.md
LICENSE

Maintainers