Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,123 @@
+---
+license: cc-by-4.0
+base_model: Qwen/Qwen2.5-1.5B-Instruct
+datasets:
+  - thirdExec/synthetic-seismic-vlm
+  - GeoGPT-Research-Project/GeoGPT-CoT-QA
+  - gOLIVES/CRACKS
+language:
+  - en
+tags:
+  - seismic
+  - fault-interpretation
+  - vision-language
+  - geophysics
+  - grounding
+  - lora
+  - peft
+---
+
+# SeisGround — trained weights
+
+Vision–language weights for **seismic fault interpretation**: a frozen seismic encoder measures
+fault geometry (count, location, dip, throw, per-fault mask); a language model then **copies those
+measured numbers** into tagged narration through a non-differentiable digit seam, so the text can only
+state values the vision reader actually measured.
+
+**Pipeline:** `frozen SFM-Base-512 encoder → DETR reader (48 queries, Hungarian, ∅) → digit-copy seam → Qwen2.5-1.5B LM narrator (LoRA)`.
+
+> ⚠️ **The encoder is NOT in this repo.** These weights run *on top of* the third-party **Seismic
+> Foundation Model** (ViT-B/16 @512), which we use **frozen and unmodified**. Download it from the
+> authors: [shenghanlin/SeismicFoundationModel](https://github.com/shenghanlin/SeismicFoundationModel#rocket-model-zoo-data-release)
+> (Sheng et al., [arXiv:2309.02791](https://arxiv.org/abs/2309.02791)) and place it at
+> `hybrid/checkpoints/SFM-Base-512.pth`.
+>
+> Code, scripts, and setup: **[github.com/Thirdbot/ModelV2](https://github.com/Thirdbot/ModelV2)** (see `SETUP.md`).
+
+## What each file is — and which result it backs
+
+The repo mirrors the code's `hybrid/checkpoints/` tree, so `hf download … --local-dir hybrid/checkpoints`
+reconstructs a runnable layout with no path surgery.
+
+### Main pipeline (synthetic training → deployable narration)
+| File | What it is | Backs |
+|---|---|---|
+| `reader.pt` | Synthetic **base reader** — DETR set-prediction that measures fault count/location/dip/throw + per-fault mask. | Synthetic vision table (pooled IoU 0.230, det F1 0.433, class 0.93, dip 28.06° vs const 32.19°, throw 53.60 vs 56.23 ms) |
+| `stage2_grounding.pt` | Grounding-stage LM adapter — teaches the narrator to read the digit seam. | (pipeline component) |
+| `stage3_narrator.pt` | **Deployed narrator** (grounding+fuse LoRA) — free-generates tagged narration that copies the measured facts. | Faithfulness table (copy 0.77 GT-injected / 0.89 reader-piped; CHAIR$_I$ 0.185; dip-swap 16/16) |
+| `stage3_answer.pt` | Answer-fold narrator variant (the `</think>→<answer>` fold). | (ablation / alternate narration) |
+| `stage1_e12dcce6ed/` | **Geology LoRA adapter** — Qwen2.5-1.5B-Instruct, r16/α16, lr 2e-5, 4-bit, trained on GeoGPT-CoT-QA. Frozen thereafter; supplies the `<think>/<answer>` reasoning scaffold. | Geology stage-1 |
+
+### Real-field A/B + ratio-selection track (`ab_experiment/`)
+Real adapters (r32, base frozen, zero-init residual) trained on top of a fresh synthetic base.
+See `ab_experiment/PROVENANCE.md` for the full identity config.
+
+| File | What it is | Backs |
+|---|---|---|
+| `ab_experiment/reader_synth.pt` | Synthetic reader **base** for this track (the frozen substrate the real adapters sit on). | — |
+| `ab_experiment/B_joint.pt` | **DEPLOYED model.** 1:1:1 joint round-robin real adapter **with** real dip/throw supervision (`TRAIN_MEASURE=1`, data-gated to Smeaheia). | A/B table (B row) + all deployed inference |
+| `ab_experiment/A_joint.pt` | Control — same 1:1:1, **no** real attribute supervision (`TRAIN_MEASURE=0`). Identical to B except the measurement heads never see real dip/throw. | A/B table (A row) |
+| `ab_experiment/ratio1.pt`, `ratio2.pt` | The two **non-selected** mixing ratios (4:3:3 and 8:1:1) from ratio selection. 1:1:1 won on held-out val (mean det F1 0.363 vs 0.333 vs 0.166) and became A/B. | Ratio-selection table |
+| `ab_experiment/alone_cracks.pt`, `alone_smeaheia.pt` | Single-survey **"alone" baselines** (no joint mixing). | Zero-shot / alone / joint table |
+
+> If you release only a subset, keep the rows for the files you actually upload. `A_joint` is the
+> paper's control; deployment needs only `B_joint` (+ `reader`, `stage3_narrator`, the geology adapter, and the SFM link).
+
+## How to use
+
+```bash
+# 1) get the weights (mirrors hybrid/checkpoints/)
+hf download thirdExec/seisground-weights --local-dir hybrid/checkpoints
+# 2) add the frozen SFM encoder (third-party — see the note above) → hybrid/checkpoints/SFM-Base-512.pth
+# 3) run inference (from the ModelV2 repo)
+DATASET=synthetic python -m hybrid.eval.inference                                        # in-distribution
+DATASET=thebe READER=hybrid/checkpoints/ab_experiment/B_joint.pt python -m hybrid.eval.inference   # a real survey
+IMAGE=path/to/section.png READER=hybrid/checkpoints/ab_experiment/B_joint.pt python -m hybrid.infer  # your own image
+```
+The narrator defaults to `stage3_narrator.pt`; override with `CKPT=` / `NARRATOR=`.
+
+## Training data
+
+| Dataset | Role | Source |
+|---|---|---|
+| Synthetic seismic VQA (1,261 scenes / 1,320 regions) | full supervision — masks, attributes, narration | [`thirdExec/synthetic-seismic-vlm`](https://huggingface.co/datasets/thirdExec/synthetic-seismic-vlm) |
+| GeoGPT-CoT-QA | geology reasoning scaffold (stage 1) | [`GeoGPT-Research-Project/GeoGPT-CoT-QA`](https://huggingface.co/datasets/GeoGPT-Research-Project/GeoGPT-CoT-QA) |
+| Thebe (37,796 patches) | real fault masks | Kaggle `mycarta/thebe-fault-patches-256` / Harvard Dataverse DOI [10.7910/DVN/YBYGBK](https://doi.org/10.7910/DVN/YBYGBK) |
+| CRACKS (397) | real fault masks | [`gOLIVES/CRACKS`](https://huggingface.co/datasets/gOLIVES/CRACKS) |
+| Smeaheia (430, GN1101 3-D cube) | real masks + independent dip/throw GT | [co2datashare.org](https://co2datashare.org/dataset/smeaheia-dataset) |
+
+## Identity config (defines the numbers)
+
+Encoder SFM-Base-512 frozen (d768/depth12/patch16/img512/tile512/grid32) · loss Focal-Tversky
+α0.4/β0.6/γ1.0, POS_WEIGHT_MAX 15, clDice 1.0 · N_QUERIES 48 · DET_TAU 0.1 · DET_THRESH 0.9 ·
+**DILATE_R 0 (pure masks, 16px floor)** · geology LoRA r16/α16 lr2e-5 4-bit · reader lr1e-4
+(encoder frozen) · grounding lr1e-4 · fold lr2e-5 · real adapter r32 lr1e-4 · ACTIVE_CLASSES=fault ·
+TOTAL_STEPS 100000 (1 round-robin epoch) · **single seed 42**.
+
+Trained on **RTX 3090 Ti 24 GB / 62 GB RAM**; Python 3.13, CUDA 12.8, torch 2.10, transformers 5.5,
+peft 0.19, trl 0.21. The method is VRAM-agnostic — only compute-layout knobs (batch, grad-ckpt, cache
+cap) change to fit smaller GPUs; the identity config, and therefore the result, does not move.
+
+## Provenance & honest limits
+
+- **Single run, seed pinned** (`SEED=42` in the training entry points) — not multi-seed averaged.
+  Small-margin metrics (CRACKS det F1, dip parity, low-count Smeaheia) carry run variance; CUDA kernels
+  are not bit-deterministic.
+- **Masks are pure (DILATE_R 0).** Segmentation numbers are at zero dilation; they are **not**
+  comparable to any dilated (DILATE_R > 0) evaluation.
+- **Two Thebe builds are not comparable.** These A/B weights use the 37,796-patch Kaggle build (pure
+  masks). Do not compare their mask numbers to any older dilated-mask Thebe result.
+- The narrator **copies** measured facts (digit seam); it does not regress numbers and cannot state a
+  value the reader did not measure. Out-of-domain prompts are answered against the on-screen seismic
+  scene, not as a general chatbot.
+
+## License
+
+Weights released under **CC-BY-4.0** *(confirm/adjust before publishing)*. Derived from
+Qwen2.5-1.5B-Instruct (Apache-2.0) via LoRA; respect the upstream licenses of the SFM encoder and each
+training dataset. The SFM encoder itself is **not redistributed here** — obtain it from its original release.
+
+## Citation
+
+If you use these weights, cite the paper (see the GitHub repo for the current reference) and the
+underlying assets: the SFM encoder (Sheng et al., 2023), GeoGPT-CoT-QA, Thebe, CRACKS, and Smeaheia.