SPIDER Documentation

SPIDER is a toolkit for probabilistic differential earthquake relocation with neural travel-time surrogates and scalable MCMC inference.

This documentation is organized for practical run setup first, then deeper technical reference.

User Guide

• Quickstart
  • Installation
  • Minimal workflow
  • Validate configuration first
  • Outputs
• Input Data Formats
  • Event catalog (io.catalog_infile)
  • Station table (io.station_file)
  • Differential times (io.dtime_file)
• Configuration Overview
  • Top-level blocks
  • io
  • model
  • inference
  • observability
  • High-impact settings to validate early
• Configuration Reference (config_v2)
  • io block
  • model block
  • model.likelihoods.sample.shared_event_re
  • inference block
  • observability block
• Probability Model and Symbol Mapping
  • Quick equation summary
  • Notation conventions
  • 1) Forward model and residuals
  • 2) Independent residual likelihood family (Phase 1 robust path)
  • 3) Correlated shared-event likelihood (Phases 2-4 sampling path)
  • 4) Priors
  • 5) Training objective (negative log posterior)
  • 6) Symbol-to-config mapping
  • 7) Which likelihood is active in each stage
• Sampler Options and Mathematical Updates
  • Available sampler backends
  • Common runtime conventions
  • Preconditioner options
  • pSGLD backend
  • SGHMC backend
  • LRD preconditioner math
  • What is currently exposed in config
  • Practical tuning interpretation
• CLI Workflow
  • Main commands
  • Typical run order
• Post-processing and Analysis Tools
  • 1) Load samples
  • 2) Build event summaries
  • 3) ESS diagnostics
  • 4) Wasserstein prior-vs-posterior diagnostics
  • 5) Plotting tools
  • 6) Typical post-processing workflow
• Outputs and File Formats
  • Output paths (io block)
  • Catalog output (catalog_outfile)
  • Samples HDF5 (samples_outfile)
  • Checkpoints (checkpoint_dir)
  • Phase-2 bundle artifacts
  • Multi-chain merged sample files
• PCG Whitening: Convergence and Fallback Control
  • Preconditions
  • Critical knobs
  • Correlation model
  • Group caps (most important for fallback)
  • PCG convergence controls
  • Safety behavior
  • Convergence-first baseline config
  • What to monitor
  • Fallback elimination playbook
  • Notes on optional solver knobs
• Sampler Health Checks
  • Core diagnostics
  • Suggested targets
  • If exploration looks too cold
  • Robust validation protocol
• Diagnostics Catalog
  • Configuration location
  • Core diagnostics switches
  • W&B group gating
  • Sampler diagnostics metrics
  • Shared-event whitening diagnostics metrics
  • Online ESS diagnostics (ess_online)
  • Practical logging profile
• Troubleshooting
  • torch.compile warning on Python 3.13+
  • Shared-event PCG fallback warning
  • Sampler instability at higher LR

Reference

• API Reference (High Level)
• Citation