Convergent representations of elastic-wave structure
Code and model release for the manuscript “Convergent representations of elastic-wave structure emerge across deliberately distinct seismic training routes.”
The scientific comparison is between deliberately heterogeneous training pathways: PNSN is a focused Pg/Sg/Pn/Sn phase picker, whereas SeismicXM is a broader multi-task waveform model. Their agreement is used to test for a reusable elastic-wave representation; parameter scaling is not the axis of comparison.
Seismic transfer does not require parameter scaling; it requires learning reusable elastic-wave structure.
Contents
experiments/2026-08-26-cross-scale-waveform-transfer/: primary RF, AE, NCF, matched-random, convergence, ensemble, residual, baseline and uncertainty programs.experiments/2026-08-29-pnsn-final-state-dispersion/: PNSN final-state and endpoint dispersion readout controls.experiments/2026-08-29-phasenet-eqtransformer-ae-transfer/: native-output AE tests for the PhaseNet and EQTransformer results promoted to main Fig. 2.experiments/2026-08-29-phasenet-eqt-ncf-readouts/: supplementary architecture-native NCF readouts for PhaseNet and EQTransformer.experiments/2026-08-30-four-model-ae-convergence/: common-input four-model learning-delta matrix, bootstrap and correspondence-permutation analysis.model_definitions/: the exact PNSN and SeismicXM PyTorch definitions needed by the programs.models/: the four released upstream checkpoints and SeisBench metadata used in the manuscript.scripts/check_reported_results.py: smoke/regression proof that recomputes the headline RF, AE and NCF values from deposited artifacts and asserts the primary convergence statistics.scripts/check_manuscript_consistency.py: submission gate that verifies checkpoint lineage and checks the artifact-derived claims in the main text and Supplementary Information, including the exploratory four-model matrix.reproducibility/: the complete curated archive of formal checkpoints, run configurations, histories, predictions, validation-selection records, uncertainty outputs, locked manifests and derived figure values.docs/: data contract, execution map, model provenance and licensing notes.
Installation
git xet install
git clone https://huggingface.co/cangyeone/elastic-wave-structure-emerge
cd elastic-wave-structure-emerge
conda env create -f environment.yml
conda activate elastic-wave-structure-emerge
python scripts/verify_release.py
When the manuscript repository is checked out beside this repository, run the cross-repository submission gate with:
python scripts/verify_release.py --full \
--manuscript-dir ../overleaf-paper \
--check-submission-tex
The versions in environment.yml reproduce the final local software environment. CPU and Apple MPS are supported by the released runners; CUDA can be added in a local PyTorch environment, but the historical command-line interface exposes CPU/MPS because those were the executed devices.
Data status
Raw training and evaluation data are not included in this release. The datasets are cited or governed by their original sources; no HDF5 corpus, NumPy waveform array, preprocessed input trace, feature cache or descriptor cache is redistributed here.
The receiver-function arrays are publicly downloadable from the repository associated with Gong et al., which does not declare a data license. The AE records are held in the restricted-access AEbagging Zenodo deposition (DOI 10.5281/zenodo.15110538); its record metadata specify CC BY 4.0, and access requests are handled through Zenodo. The ambient-noise correlations and dispersion targets are publicly available without gating from SeisDispFusion-NCF revision afcd805 (DOI 10.57967/hf/9114) under Apache-2.0. That processed release derives its NCF waveforms from the CC BY 4.0 Mendeley Data source; both NCF releases should be cited. These source datasets are cited rather than duplicated here.
The repository does include the products needed to audit the reported computations without confusing them with source data: path-sanitized locked split manifests, source-file hashes, formal configurations, trained downstream checkpoints, histories, validation selections, test predictions, bootstrap/permutation outputs, aggregate tables and non-waveform figure values. It also includes a compact NCF implicit-geometry summary containing only split sizes and six correlations; the source waveforms and feature cache used to derive it remain excluded. These products are publicly distributed as derived reproducibility artifacts under this repository's GPL-3.0 license, not as copies of the cited input datasets. The historical manifests use ${RF_DATA_DIR}, ${AE_TRAIN_H5}, ${AE_TEST_H5} and ${NCF_H5} placeholders in place of machine-local paths.
After obtaining the datasets, create the locked, leakage-audited manifests with explicit paths:
python experiments/2026-08-26-cross-scale-waveform-transfer/prepare_manifests.py \
--rf_dir /path/to/rf/data \
--rf_reference_split /path/to/split_indices.npz \
--ae_train /path/to/AE_train.h5 \
--ae_test /path/to/AE_test.h5 \
--ncf_h5 /path/to/ncf_disp_dataset.h5
See docs/DATA.md for the expected schemas and data-source boundary, docs/REPRODUCIBILITY.md for the execution order, and reproducibility/README.md for the artifact map. The exact main-figure generators are deposited under scripts/manuscript_figures/; they consume the archived derived results plus locally obtained cited inputs.
Checkpoints
| Path | Role | Complete parameters | Retained representation parameters | SHA-256 |
|---|---|---|---|---|
models/pnsn/pnsn.v3.pt |
focused four-phase PNSN pathway | 450,485 | 345,600 | 9f626e5fff4e9390c88e43c2f6230802496163b5d6eefee05e1b6ac7ccebf9e8 |
models/seismicxm/seismicxm.middle.pt |
official multi-task SeismicXM middle pathway | 51,895,545 | 41,332,096 | 671d02d677c25c3d075963889602299ec71f52c724470f2fa85bb28035fe1528 |
models/phasenet/original.pt.v2 |
PhaseNet native-AE generality route and exploratory geometry control | 268,443 | -- | 184dd85b896eebf8d5967ee15a722a477fa2e4ce479a3b113ecbcb8a6419113f |
models/eqtransformer/original.pt.v3 |
EQTransformer native-AE generality route and exploratory geometry control | 376,935 | -- | c363c59dfb4562ba3b1356fb03dc9c776bbcfe3384b5db22e5ee3689de0a4df9 |
For PNSN and SeismicXM, the retained count is the frozen representation path used by the downstream analyses and excludes source decoders and target readouts. python scripts/audit_model_parameters.py strictly reloads both checkpoints and reproduces the detailed component-level counts. The reproducibility archive also contains all 338 saved downstream checkpoints from the completed primary runs: 240 formal paired runs and 98 temporal, residual and specialized-baseline runs. Supplementary architecture-native runs that did not save a head checkpoint retain their complete histories, metrics and predictions. Interrupted, smoke-test and quarantine runs are excluded. Full model and license provenance is in docs/MODELS.md.
License and citation
The repository's derived code is released under GPL-3.0. PhaseNet and EQTransformer checkpoint files retain their upstream MIT terms and attribution. See docs/MODELS.md before redistribution. Cite this archive using DOI 10.57967/hf/10158, together with the manuscript and the four upstream model publications listed in CITATION.cff and the provenance document.